Search results

Swagger UI tutorial

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

I'm giving an API documentation workshop in Mountain View, California on August 30, 2019. If you're interested, you can register on EventBrite.

Swagger UI provides a display framework that reads an OpenAPI specification document and generates an interactive documentation website. The following tutorial shows you how to integrate an OpenAPI specification document into Swagger UI.

For a more conceptual overview of OpenAPI and Swagger, see Introduction to the OpenAPI specification and Swagger. For a step-by-step tutorial on creating an OpenAPI specification document, see the OpenAPI tutorial.

Swagger UI overview

Swagger UI is one of the most popular tools for generating interactive documentation from your OpenAPI document. Swagger UI generates an interactive API console for users to quickly learn about your API and experiment with requests. Additionally, Swagger UI (which is an actively managed project with an Apache 2.0 license) supports the latest version of the OpenAPI spec (3.x) and integrates with other Swagger tooling.

For definitions of common terms, see Key terms at the end of this article.

Get familiar with Swagger UI through the Petstore demo

To get a better understanding of Swagger UI, let’s explore the Swagger Petstore example. In the Petstore example, the site is generated using Swagger UI.

Petstore UI

The endpoints are grouped as follows:

Authorize your requests

Before making any requests, you would normally authorize your session by clicking the Authorize button and completing the information required in the Authorization modal pictured below:

Authorization modal in Swagger UI

The Petstore example has an OAuth 2.0 security model. However, the authorization code is just for demonstration purposes. There isn’t any real logic authorizing those requests, so you can simply close the Authorization modal.

Make a request

Now let’s make a request:

  1. Expand the POST Pet endpoint.
  2. Click Try it out.

    Try it out button in Swagger UI

    After you click Try it out, the example value in the Request Body field becomes editable.

  3. In the Example Value field, change the first id value to a random integer, such as 193844. Change the second name value to something you’d recognize (your pet’s name).
  4. Click Execute.

    Executing a sample Petstore request
    Executing a sample Petstore request

    Swagger UI submits the request and shows the curl that was submitted. The Responses section shows the response. (If you select JSON rather than XML in the “Response content type” drop-down box, the response’s format will be shown in JSON.)

    Response from Swagger Petstore get pet request

Verify that your pet was created

  1. Expand the GET /pet/{petId} endpoint.
  2. Click Try it out.
  3. Enter the pet ID you used in the previous operation. (If you forgot it, look back in the POST Pet endpoint to check the value.)
  4. Click Execute. You should see your pet’s name returned in the Response section.

Some sample Swagger UI doc sites

Before we get into this Swagger tutorial with another API (other than the Petstore demo), check out a few Swagger implementations:

Some of these sites look the same, but others, such as The Movie Database API and Zomato, have been integrated seamlessly into the rest of their documentation website.

Looking at the examples, you’ll notice the documentation is short and sweet in a Swagger implementation. This brevity is because the Swagger display is meant to be an interactive experience where you can try out calls and see responses — using your own API key to see your own data. It’s the learn-by-doing-and-seeing-it approach. Also, Swagger UI only covers the reference topics of your documentation. The conceptual topics are usually covered in a separate guide.

Activity: Create a Swagger UI display with an OpenAPI spec document

In this activity, you’ll create a Swagger UI display for an OpenAPI specification document. If you’re using one of the pre-built OpenAPI files, you can see a demo of what we’ll build here: OpenWeatherMap Swagger UI or Sunrise/sunset Swagger UI.

Demo of Swagger UI
Demo of Swagger UI rendering an OpenWeatherMap OpenAPI specification document

To integrate your OpenAPI spec into Swagger UI:

  1. Prepare a valid OpenAPI specification document:
  2. Make sure your OpenAPI specification is valid. Paste your OpenAPI specification code into the Swagger online editor and make sure no warnings appear. The view on the right of the Swagger Editor shows a fully functional Swagger UI display.

  3. Go to the Swagger UI GitHub project.
  4. Click Clone or download, and then click Download ZIP. Download the files to a convenient location on your computer and extract the files.

    The only folder you’ll be working with in the downloaded zip is the dist folder (short for distribution). Everything else is used only if you’re recompiling the Swagger files, which is beyond the scope of this tutorial.

  5. Drag the dist folder out of the swagger-ui-master folder so that it stands alone. (Then optionally delete the swagger-ui-master folder and zip file.)
  6. Drag your OpenAPI specification file (from step 1) into the dist folder. (If you’re using the pre-build OpenAPI files, the file is called either openapi_openweathermap.yml or openapi_sunrise_sunset.yml.) Your file structure should look as follows:

    ├── dist
    │   ├── favicon-16x16.png
    │   ├── favicon-32x32.png
    │   ├── index.html
    │   ├── oauth2-redirect.html
    │   ├── swagger-ui-bundle.js
    │   ├── swagger-ui-bundle.js.map
    │   ├── swagger-ui-standalone-preset.js
    │   ├── swagger-ui-standalone-preset.js.map
    │   ├── swagger-ui.css
    │   ├── swagger-ui.css.map
    │   ├── swagger-ui.js
    │   ├── swagger-ui.js.map
    │   ├── swagger30.yml
    │   └── [your openapi specification file]
    
  7. Inside your dist folder, open index.html in a text editor such as Atom editor or Sublime Text.
  8. Look for the following code:

    url: "http://petstore.swagger.io/v2/swagger.json",
    
  9. Change the url value from http://petstore.swagger.io/v2/swagger.json to a relative path to your YAML file, and then save the file. For example

    url: "openapi_openweathermap.yml",
    

    or

    url: "openapi_sunrise_sunset.yml",
    
  10. View the index.html file locally in your browser. Note that Chrome’s security restrictions (CORS objections) prevent you from viewing the Swagger UI file locally. You have several workarounds:

When you’re ready to publish your Swagger UI file, you simply upload the folder to a web server and go to the index.html file. For example, if you called your directory dist (leaving it unchanged), you would go to http://myserver.com/dist/. (You can change the “dist” folder name to whatever you want.)

For more instructions in working with Swagger UI, see the Swagger.io docs.

Configuring Swagger UI parameters

Swagger UI provides various configuration parameters (unrelated to the OpenAPI parameters) that you can use to customize the interactive display. For example, you can set whether each endpoint is expanded or collapsed, how tags and operations are sorted, whether to show request headers in the response, whether to include the Models section after the list of endpoints, and more.

We won’t get too much into the details of these configuration parameters in the tutorial. I just want to call attention to these parameters here for awareness.

If you look at the source of my Swagger UI demo (go to View > Source), you’ll see the parameters listed in the // Build a system section:

  // Build a system
const ui = SwaggerUIBundle({
  url: "openapi_openweathermap.yml",
  dom_id: '#swagger-ui',
  defaultModelsExpandDepth: -1,
  deepLinking: true,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl
  ],
  layout: "StandaloneLayout"
})

The parameters there (e.g., deepLinking, dom_id, etc.) are defaults. However, I’ve added defaultModelsExpandDepth: -1 to hide the “Models” section at the bottom of the Swagger UI display (because I think that section is unnecessary).

You can also learn about the Swagger UI configuration parameters in the Swagger documentation.

Challenges with Swagger UI

As you explore Swagger UI, you may notice a few limitations:

  • There’s not much room to describe in detail the workings of the endpoints. If you have several paragraphs of details and gotchas about a parameter, it’s best to link out from the description to another page in your docs. The OpenAPI spec provides a way to link to external documentation in both the paths object, the info object, and the externalDocs object
  • The Swagger UI looks mostly the same for each API. You can customize Swagger UI with your own branding, but it will some more in-depth UX skills. It is, however, relatively easy to change the color and image in the top navigation bar.
  • The Swagger UI might be a separate site from your other documentation. This separate output means that in your regular docs, you’ll probably need to link to Swagger as the reference for your endpoints. You don’t want to duplicate your parameter descriptions and other details in two different sites. See Integrating Swagger UI with the rest of your docs for strategies on unifying your reference docs and user guide.

Troubleshooting issues with Swagger UI

When you’re setting up Swagger UI, you might run into some issues. The following issues are the most common:

CORS issues:

If you have security correctly configured, but the requests are rejected, it could be due to a CORS (cross-origin resource sharing) issue. CORS is a security measure that websites implement to make sure other scripts and processes cannot take their content through requests from remote servers. See CORS Support in Swagger UI’s documentation for details.

If the requests aren’t working, open your browser’s JavaScript console (in Chrome, View > Developer > Javascript Console) when you make the request and see if the error relates to cross-origin requests. If so, ask your developers to enable CORS on the endpoints.

Host URL issues:

The host for your test server might be another reason that requests are rejected. Some APIs (like Aeris Weather) require you to create an App ID that is based on the host URL where you’ll be executing requests. If the host URL you registered is http://mysite.com, but you’re submitting the test from https://editor.swagger.io/, the API server will reject the requests.

If you need help, the Swagger Google Group is a helpful resource for troubleshooting.

Embedding Swagger UI within an existing site

In addition to publishing your Swagger UI output as a standalone site, you can also embed the Swagger file within an existing site. See the following:

Since the Swagger UI site is responsive, it resizes well to fit into most any space. Even so, embedding Swagger into an existing site still looks like a website within a website.

Key terms

Swagger
Refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. For more tools, see Swagger Tools. “Swagger” was the original name of the OpenAPI spec, but the name was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. People sometimes refer to both names interchangeably (especially on older web pages), but “OpenAPI” is how the spec should be referred to. For more on naming conventions between OpenAPI and Swagger, see What Is the Difference Between Swagger and OpenAPI?.
OpenAPI
The official name for the OpenAPI specification. The OpenAPI specification provides a set of properties that can be used to describe your REST API. When valid, the specification document can be used to create interactive documentation, generate client SDKs, run unit tests, and more. You can read the specification details on GitHub at https://github.com/OAI/OpenAPI-Specification. Under the Open API Initiative with the Linux Foundation, the OpenAPI specification aims to be vendor neutral (many companies steer its development, not just one).
Swagger Editor
An online editor that validates your OpenAPI document against the rules of the OpenAPI specification. The Swagger Editor will flag errors and give you formatting tips. See Swagger Editor.
Swagger UI
An open-source web framework (on GitHub) that parses an OpenAPI specification document and generates an interactive documentation website. Swagger UI is the tool that transforms your spec into the Petstore-like site.
Swagger Codegen
Generates client SDK code for a lot of different platforms (such as Java, JavaScript, Scala, Python, PHP, Ruby, Scala, and more). The client SDK code helps developers integrate your API on a specific platform and provides for more robust implementations that might include more scaling, threading, and other necessary code. In general, SDKs are toolkits for implementing the requests made with an API. Swagger Codegen generates the client SDKs in nearly every programming language. See Swagger Codegen for more information. See also SDKs and sample apps.
49% Complete

49/120 pages complete. Only 71 more pages to go.

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.