Downloading OpenAPI Definitions From SwaggerHub

Last modified on April 14, 2021

SwaggerHub lets you download the OpenAPI (Swagger) definition of any API or domain in the YAML or JSON format.

Download from SwaggerHub Editor

  1. Open the API in the SwaggerHub editor.

  2. If the API has several versions, select the version you want to download.

    Selecting an API version
  3. From the Export menu, select Download API, and then select the desired format – YAML or JSON.

    Downloading an OpenAPI definition as YAML or JSON

There are options to download either a resolved or an unresolved definition. This makes a difference if your definition includes external $ref links, such as links to domains.

  • Unresolved means external links will not be resolved, and the resulting file will contain the $ref links as they appear in the editor.

  • Resolved means external links will resolved, that is, the contents of external files will be included in the resulting definition.

Download via a URL

Public APIs

A quick way to download OpenAPI definitions from SwaggerHub is to replace app with api in the address bar, as shown below. If the URL ends with a permalink to a tag or operation, such as #/pets, remove that part.

Downloading an API definition from the address bar

In SwaggerHub On-Premise, add /v1 after the host name instead:

Downloading an API definition from the address bar

The download URL has the following format:

https://api.swaggerhub.com/apis/{owner}/{api}/{version}         # SwaggerHub SaaS
http(s)://{swaggerhub-host}/v1/apis/{owner}/{api}/{version}     # SwaggerHub On-Premise

You can also use tools like cURL to download definitions from SwaggerHub:

curl https://api.swaggerhub.com/apis/swagger-tutorials/petstore/1.0.0

This downloads the API definition as JSON. If you want YAML, either append /swagger.yaml at the end, or use the Accept: application/yaml header:

curl https://api.swaggerhub.com/apis/swagger-tutorials/petstore/1.0.0/swagger.yaml
curl -H "Accept: application/yaml" https://api.swaggerhub.com/apis/swagger-tutorials/petstore/1.0.0

Resolved YAML/JSON

This information applies to SwaggerHub SaaS, SwaggerHub On-Premise 1.25.0 and later.

To get a resolved API definition, append ?resolved=true to the download URL.

Resolved YAML:

https://api.swaggerhub.com/apis/{owner}/{api}/{version}/swagger.yaml?resolved=true

Resolved JSON:

https://api.swaggerhub.com/apis/{owner}/{api}/{version}?resolved=true

In SwaggerHub On-Premise:

http(s)://{swaggerhub-host}/v1/apis/{owner}/{api}/{version}/swagger.yaml?resolved=true
http(s)://{swaggerhub-host}/v1/apis/{owner}/{api}/{version}?resolved=true

Private APIs

If the API definition is private, add the Authorization: API_KEY header containing your SwaggerHub API key:

curl -H "Authorization: API_KEY" https://api.swaggerhub.com/apis/{owner}/{api}/{version}

Maven and Gradle plugins

SwaggerHub has plugins for Maven and Gradle that allow you to download API definitions as part of your CI/CD pipeline.

See Also

Generating a Client SDK
Generating a Server Stub

Highlight search results