Swagger UI tutorial

Swagger UI provides a display framework that reads the 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.

Terminology notes

First, let’s clarify a few terms:

  • Swagger was the original name of the spec, but the spec was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. People sometimes refer to both names interchangeably (esp. on older web pages), but “OpenAPI” is how the spec should be referred to.
  • The OpenAPI spec is driven by the OpenAPI initiative, backed by the Linux Foundation and steered by many companies and organizations. The Swagger YAML file that you create to describe your API is called the “OpenAPI specification document.”
  • Swagger refers to API tooling that around the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear.
  • SwaggerHub is the more fully featured, commercial version of the open-source Swagger UI. See Swagger UI on Swagger.io for a feature comparison.

For more details, see What Is the Difference Between Swagger and OpenAPI? and the API Glossary.

This tutorial focuses on Swagger UI. For a deep dive into the OpenAPI spec, see my OpenAPI tutorial here.

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.

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 into three tags:

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 demo 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, you can specify that JSON is returned rather than XML.)

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.

Create a Swagger UI display with an OpenAPI spec document

In this activity, you’ll create a Swagger UI display for the weatherdata endpoint in this Mashape Weather 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.

Swagger UI demo

You can also follow instructions for working with Swagger UI here 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, copy this sample OpenAPI file by right-clicking the link and saving the file (“openapi_weather.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 here is the dist folder (short for distribution). Everything else is used only if you’re regenerating the 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 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_weather.yml",
    

    Save the file.

  8. Drag the swagger_weather.yml file that you downloaded earlier 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_weather.yml
    
  9. 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. It’s also common to run a local web server to view the Swagger UI site. To run a local web server on your computer, you can use a simple Python http server or a more robust local server such as XAMPP.

Swagger UI provides a number of 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.

Challenges with Swagger UI

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

  • 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 and the info object.
  • The Swagger UI looks mostly the same for each output. You can modify the source files and regenerate the output, but doing so requires more advanced coding 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. You can customize Swagger UI with your own branding, but it will some deeper UX skills.

Auto-generating the Swagger file from code annotations

Instead of coding the Swagger file by hand, you can also auto-generate it from annotations in your programming code. There are many Swagger libraries for integrating with different code bases. These Swagger libraries then parse the annotations that developers add and generate the same Swagger file that you produced manually using the earlier steps.

By integrating Swagger into the code, you allow developers to easily write documentation, make sure new features are always documented, and keep the documentation more current. Here’s a tutorial on annotating code with Swagger for Scalatra. The annotation methods for Swagger doc blocks vary based on the programming language.

For other tools and libraries, see Swagger services and tools and Open Source Integrations.

Sorting out the various Swagger tools

As I explained earlier, Swagger refers to the various API tools built around the OpenAPI spec. Here’s a quick summary of what Swagger tools are available:

  • Swagger editor: The Swagger Editor is an online editor that validates your OpenAPI document against the rules of the OpenApI spec. You’ll need to be familiar with OpenAPI specification to be successful here. The Swagger editor will flag errors and give you formatting tips. See my OpenAPI tutorial for a step-by-step walkthrough.
  • Swagger-UI: The Swagger UI is an HTML/CSS/JS framework that parses an OpenAPI specification document and generates an interactive documentation website. This is the tool that transforms your spec into the Petstore-like site.
  • Swagger-codegen: This tool 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.
  • Swaggerhub: The commercial version of the open-source Swagger UI project.

For more tools, see Swagger Tools.

66% Complete

66/91 pages complete. Only 25 more pages to go...

Get new posts delivered straight to your inbox.

Subscriber count: 4,285