Apiary supports Swagger as the API Description format. This page will help you to use Swagger within Apiary ecosystem.

swagger-announcement-graphic Created with Sketch.

Apiary supports
Swagger

Read more Read more
Tip

Can’t choose between API Blueprint or Swagger? Take a look at choosing API Description format

Importing your Swagger into Apiary

When creating new API, you can select Swagger document as preset. Alternatively, you can simply paste your Swagger document into Apiary Editor.

Swagger format

Swagger YAML is the primary Swagger format in Apiary. However, if you paste Swagger JSON into the editor, it’ll be automatically transformed for you.

Creating Swagger API

Choosing Swagger on Welcome page

After registration, you are are redirected to welcome page where you can choose name and format of the API.

Welcome page

Don’t worry. You can change the format of the API any time by entering the API Description code in your chosen format.

Choosing Swagger when creating new API

You have the option to choose Swagger also when creating new API.

New API modal

Documentation

After saving your document, our interactive documentation and Mock server will be immediately available for you.

Supported Swagger Versions

Please note that Apiary currently only supports Swagger 2.0

Supported Apiary functionality for Swagger projects

Known limitations

  1. Only the first scheme will be used to create a hostname from the schemes
  2. External documentation as externalDocs is not yet supported
  3. Body parameters on the Swagger Object and Path Item Object are not yet supported
  4. Default response is not yet supported
  5. Tags have limited support. If there are items with multiple tags, the tags will be ignored.
  6. Certain metadata is not used, such as contact, license, and termsOfService
  7. The deprecated value on an Operation Object is currently not supported
  8. The formData parameters are currently not supported with GET operations (including Path). POST support is limited.
  9. ssv, tsv and pipes values for collectionFormat on a Parameter Object are not supported.
  10. Array type in form parameters is not supported.
  11. JSON Examples are nnot generated from JSON Schemas that conntain circular references.
  12. Multi-file referencing is not supported.
  13. API key defined in security section of Swagger description is not visible in request header when performing a call in Console.

Apiary vendor extensions

While there are things we do not support, there are also things we support that Swagger cannot handle. We are currently working on ways around this, and have used vendor extensions in one place to provide this additional functionality.

Was this page useful?
Thank you for the feedback!
What went wrong?