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.

Create a Swagger UI display with an OpenAPI spec document

Activity

In this activity, you’ll create a Swagger UI display for the weather endpoint in this OpenWeatherMap API. (If you’re jumping around in the documentation, this is a simple API that we used in earlier parts of the course.) You can see a demo of what we’ll build here.

Demo of Swagger UI rendering an OpenWeatherMap OpenAPI specification document

You can also follow instructions for working with Swagger UI in the Swagger.io docs.

To integrate your OpenAPI spec into Swagger UI:

  1. If you don’t already have an OpenAPI specification document, follow the OpenAPI tutorial here to create one. The tutorial here focuses on Swagger UI, so for convenience, you can also copy this sample OpenAPI file by right-clicking the link and saving the file (“openapi_openweathermap.yml”) to your desktop.

    If you want to preview what your Swagger UI implementation will look like ahead of time, copy the content from the OpenAPI specification document you just downloaded into the Swagger online editor. The view on the right of the Swagger Editor shows a fully functional Swagger UI display.

  2. Go to the Swagger UI GitHub project.
  3. Click Clone or download, and then click Download ZIP button. 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.

  4. Drag the dist folder out of the swagger-ui-master folder so that it stands alone. Then delete the swagger-ui-master folder and zip file.
  5. Inside your dist folder, open index.html in a text editor such as Atom editor or Sublime Text.
  6. Look for the following code:

    url: "http://petstore.swagger.io/v2/swagger.json",
    
  7. Change the url value from http://petstore.swagger.io/v2/swagger.json to the following:

    url: "openapi_openweathermap.yml",
    

    Save the file.

  8. Configure any special Swagger UI parameters as desired.

    We won’t get too much into the details of these parameters here. I just want to call attention to them here for awareness. Swagger UI provides a number of parameters (unrelated to your OpenAPI parameters) you can use to customize the 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, and more.

    For example, 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).

  9. Drag the openapi_openweathermap.yml file that you downloaded in step 1 into the same directory as the index.html file you just edited. Your file structure should look as follows:

    ├── swagger
    │   ├── 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
    │   └── openapi_openweathermap.yml
    
  10. Upload the folder to a web server and go to the folder path. 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.)

You can also view the file locally in your browser. In Chrome, go to File > Open and browse to the index.html file in your dist folder.

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.
67% Complete

67/108 pages complete. Only 41 more pages to go...

Donate?

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

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