Search results

Swagger UI tutorial

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

Swagger UI provides a display framework that reads an OpenAPI specification document and generates an interactive documentation website. This tutorial shows you how to use the Swagger UI interface and how to integrate an OpenAPI specification document into the standalone distribution of Swagger UI.

For a more detailed conceptual overview of OpenAPI and Swagger, see Introduction to the OpenAPI specification and Swagger.

For step-by-step tutorial on creating an OpenAPI specification document, see the OpenAPI tutorial. In the tutorial, I showed how the OpenAPI specification gets rendered by the Swagger UI display that is built into the Swagger Editor. Here I explain how to use Swagger UI as a standalone output.

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 and try the API. Additionally, Swagger UI is an actively managed project (with an Apache 2.0 license) that supports the latest version of the OpenAPI spec (3.0) and integrates with other Swagger tools.

In the following tutorial, I’ll show you how to Swagger UI works and how to integrate an OpenAPI specification document into it.

Before we dive into Swagger, it might help to clarify some key terms.

The Swagger UI Petstore example

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

    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 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 Petstore), 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.

You’ll notice the documentation is short and sweet in a Swagger UI implementation. This 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.

Activity 4c: 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 that you prepared earlier (in step 1) into the the dist folder. 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. For example

    url: "openapi_openweathermap.yml",
    

    or

    url: "openapi_sunrise_sunset.yml",
    

    Save the file.

  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 a number of configuration parameters (unrelated to your OpenAPI parameters) 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 Model, 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 the Swagger UI demo, 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 (since 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 endpoint in Swagger. 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 output. You can customize Swagger UI with your own branding, but it will some deeper UX skills.
  • The Swagger UI might be a separate site from your other documentation. This means 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 more details on workarounds.
49% Complete

49/111 pages complete. Only 62 more pages to go...

Donate?

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