Interactive API Documentation

Last modified on July 21, 2021

SwaggerHub generates interactive API documentation for your OpenAPI definitions. Use it to explore the API endpoints, parameters, responses, and data models, and test the API calls directly in your browser.

Documentation-only view

Click on the SwaggerHub toolbar to view just the API documentation (or domain documentation) without the editor.

Previewing Interactive API Documentation in SwaggerHub

Click the image to enlarge it.

Copy the resulting documentation link and share it with your API consumers who need access to your API documentation.

Note: If your API is private, you will need to add consumers as collaborators with the View role so that they can view your API documentation

API documentation pages follow the same naming format as API and domain pages, but with the -docs suffix added after /apis (or /domains) in the address:

https://app.swaggerhub.com/apis-docs/{owner}/{name}/{version}
                                 ^
https://app.swaggerhub.com/domains-docs/{owner}/{name}/{version}
                                    ^

If you omit the version number, the documentation page will show the default version:

https://app.swaggerhub.com/apis-docs/swagger-hub/registry-api

Custom branding

This information applies to SwaggerHub SaaS only.

Organizations can add a custom logo to their API documentation to maintain the company’s brand awareness. The logo will be displayed in the consumer-facing documentation for all of the organization’s APIs and domains. See Docs Branding for details.

Custom logo in API documentation

"Try it out"

Interactive documentation lets you test API calls directly from the browser using the Try it out button. SwaggerHub will show the response headers and body, the request duration, and the cURL command that can be used to send the same request from the command line.

Testing API calls in SwaggerHub

Click the image to enlarge it.

Target server for requests

In order for “try it out” to work, your API definition must specify the host (in OpenAPI 2.0) or servers (in OpenAPI 3.0) so that SwaggerHub knows where to send requests:

swagger: '2.0'
host: myapi.com
schemes:
  - https
basePath: /v2

# or

openapi: 3.0.0
servers:
  - url: 'https://myapi.com/v2'

If you do not want to use a production server, or if you do not have one yet, you can use SwaggerHub’s mock server. The mock server will generate responses based on the response schemas and examples specified in your API definition.

Routing requests

SwaggerHub lets you send "try it out" requests directly from your browser to the target server, or proxy the requests through the SwaggerHub server. As a rule of thumb, use a browser to access local APIs, and a proxy for Internet-facing APIs.

You can change the routing mode at the bottom of the docs. The selected option is saved in the browser’s localStorage and applies to all APIs you test from this browser.

Routing options

Routing requests via SwaggerHub proxy (default)

This is the preferred mode for Internet-facing APIs. "Try it out" requests from the browser are first sent to the SwaggerHub server, which forwards the requests to the target API server. Responses from the API server are sent back to the SwaggerHub server and then to your browser. This approach avoids browser restrictions for cross-domain HTTP requests.

Routing requests via SwaggerHub proxy

Benefits:

  • No need for CORS support on the API server.

  • Supports user-defined parameters in the Cookie header.

Requirements:

  • If you use SwaggerHub SaaS, the API server must be on the public Internet and allow connections from our IP addresses. SwaggerHub On-Premise supports both Internet-facing and local servers (except localhost, 127.*.*.* and 172.18.*.*).

Limitations:

  • The request timeout is not configurable and is set to:

    • 30 seconds in SwaggerHub SaaS
    • 30 seconds in SwaggerHub On-Premise 1.21.0 and later
    • 10 seconds in earlier versions of SwaggerHub On-Premise
  • When using SwaggerHub SaaS, "try it out" requests are proxied through the SwaggerHub cloud servers. If privacy or ownership of infrastructure is a concern, use routing via browser instead, or consider using SwaggerHub On-Premise hosted on your own infrastructure.

  • In SwaggerHub On-Premise, requests cannot be sent to localhost, 127.*.*.* and 172.18.*.*.

Routing requests via browser

Supported in SwaggerHub SaaS and SwaggerHub On-Premise 1.18.7 and later.

In this mode, "try it out" requests are sent directly from the web page to the API server by using JavaScript.

Routing requests via browser

Benefits:

  • Supports both Internet-facing servers and local servers.

  • Requests are sent directly from your browser to the API server, without going through any intermediate infrastructure.

  • Requests are sent with browser cookies (but not with user-defined cookie parameters).

Requirements:

Limitations:

  • Cannot send requests to HTTP (non-secure) servers from SwaggerHub SaaS and SwaggerHub On-Premise hosted on HTTPS, because the browsers block access to insecure content from secure web pages.

  • Cannot send user-defined values in the Cookie header and other forbidden request headers.

  • Response headers displayed after "try it out" are restricted by the Access-Control-Expose-Headers response header. If this header is missing, only simple response headers are displayed.

  • The Set-Cookie response header is not displayed due to browser security restrictions.

Troubleshooting "try it out" requests

TypeError: Failed to fetch

When routing requests via browser, this error happens if:

  • the API server does not support CORS

  • request is sent from an https:// web page to an http:// (non-secure) server.

To avoid the issue, change the routing mode to Use proxy.

OpenAPI 3.0 specifics

Some features of OpenAPI 3.0 are currently not supported in the Interactive Documentation. See here for known limitations.

Lazy loading

SwaggerHub reduces the documentation load time by loading external references only when they are needed for rendering. See Lazy Loading to learn more.

See Also

SwaggerHub Editor
CORS Requirements for "Try It Out"

Watch the video
 
Highlight search results