Download API Definitions From SwaggerHub

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

Download from SwaggerHub Editor

Open the API in the SwaggerHub editor.
If the API has several versions, select the version you want to download.
From the Export menu, select Download API, and then select the desired format – 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 API definitions from SwaggerHub is to replace app with api in the address bar, as shown below.

Remove that part if the URL ends with a permalink to a tag or operation, such as #/pets

Downloading an API definition from the address bar

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

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.