Swiftpack.co - Package - AttilaTheFun/SwaggerParser

Swagger Parser

SwagerParser is a swift implementation of the OpenAPI 2.0 Specification. (F.K.A. Swagger) This library is intended for use in conjunction with templating engines like Stencil. Together, you can write templates to generate boilerplate code in the language of your choosing from API documentation.

Prerequisites

The current (and only maintained) version of SwaggerParser requires Swift 4.0+ because it uses the builtin Codable protocols. It has no dependencies and compiles for macOS 10.13. It would probably compile on linux and older versions of macOS but this is untested.

Installing

SwaggerParser is available through the Swift Package Manager. To install the package, add the following to your Package.swift file:

        .Package(url: "https://github.com/AttilaTheFun/SwaggerParser.git", majorVersion: 0, minor: 5)

And run swift package update to install the library. To use the library, import the module and try to instantiate an instance of the Swagger type, either from JSON data or a JSON string:

import SwaggerParser

...

let jsonString = // load the swagger file into a string
let swagger = try Swagger(from: jsonString)

// Prints: "Gets the user with the specified ID"
print(swagger.paths["/users/{user_id}"].operations[.get]?.description) 

Running the tests

This package has tests that can be run with swift package test or within Xcode by generating an xcodeproj with swift package generate-xcodeproj.

Contributing

Contributions are welcome, and if you find an issue with the library please report it in the github issues section. To make a contribution, fork the repository, make your changes, and open a pull request into the master branch.

Versioning

We use SemVer for versioning. Until version 1.0 is reached, minor versions can be source-breaking, but patch versions are not.

Contributors

Logan Shire - AttilaTheFun Wrote core library and ported it to Swift 4 / Codable.

Westin Newell - n8chur Contributed support for allOf, x-nullable, x-abstract, example, discriminator, and more.

Yonas Kolb - yonaskolb Contributed to parsing of metadata, versions, cyclic references, and missing operation properties.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Github

link
Stars: 13
Help us keep the lights on

Dependencies

Releases

0.6.1 - Oct 21, 2017

0.6.0 - Oct 21, 2017

This release updates the project structure to make Sources, Tests, and Fixtures top level folders. It also updates the package syntax to use Swift Package Manager tools version 4.0 which allows for the specification of source directories on a per-target basis. Now, when generating the xcodeproj it will no longer try to include the fixture files in your project. As this is a breaking change, the minor version has been increased. It also includes a bug fix for decoding Object schema, where objects were required to have properties (even if it was an empty dictionary). Now if the properties field is omitted, it's assumed to be an empty dictionary.

0.5.1 - Aug 30, 2017

0.5.0 - Aug 30, 2017

This release completely refactors the library to support Swift 4 and leverage the new Codable protocol. The ObjectMapper dependency has been removed. This release is tagged as a pre-release because Swift 4 hasn't been officially released yet. Once the Xcode 9 GM seed is released, we'll add a Readme and cut 1.0.

0.4.0 - Jul 12, 2017

Changes in this release:

  • Added Tag type and 'tags' definitions to Swagger object
  • Added ExternalDocumentation type to Schema, Operation, Swagger and Tag
  • Improved + consolidated reference resolution. Fixed a bug with cyclic references.
  • Separated Schema into Schema and SchemaType, the latter being an enum.
  • Separated Items into Items and ItemsType, the latter being an enum.
  • Extracted metadata from the enum cases into Schema and Items respectively.
  • VersionTransform is now a struct for better consistency in the API.
  • New 'multi' case for CollectionType, used for query strings "foo=a&foo=b"
  • Added / cleaned up security requirements.
  • Fixed several URL mappings that were likely failing (and untested) before.
  • Removed Reference and Pointer from the public API - they are only used during building.
  • Added more granularity to DecodingError, including a localized description, file and line numbers.
  • Made top-level parameters, definitions, and responses into dictionaries (instead of structures) for better ergonomics.

Many thanks to @n8chur and @yonaskolb for all of their feedback and contributions!