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

Read more Read more

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


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. Default response is not yet supported
  4. Tags have limited support. If there are items with multiple tags, the tags will be ignored.
  5. Certain metadata is not used, such as contact, license, and termsOfService
  6. The deprecated value on an Operation Object is currently not supported
  7. The formData parameters are currently not supported with GET operations (including Path). POST support is limited.
  8. ssv, tsv and pipes values for collectionFormat on a Parameter Object are not supported.
  9. Array type in form parameters is not supported.
  10. JSON Examples are not generated from JSON Schemas that conntain circular references.
  11. Multi-file referencing is not supported.
  12. API key defined in security section of Swagger description is not visible in request header when performing a call in Console.
  13. In a Schema Object, the following properties are not supported: readOnly, writeOnly, discriminator, ` , and externalDocs`

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.