1. I'd Rather Be Writing
2. Docs
3. Chapter 4: OpenAPI spec and generated reference docs

Swagger UI tutorial

Download PDF

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, or see this article I wrote for ISTC a few years ago: Implementing Swagger with API docs (PDF). For a step-by-step tutorial on creating an OpenAPI specification document, see the OpenAPI tutorial. Or for an easier approach using a visual editor to create the OpenAPI spec, see Getting started tutorial: Using Stoplight to create an OpenAPI specification document.

• Swagger UI overview
• Get familiar with Swagger UI through the Petstore demo
  • Authorize your requests
  • Make a request
  • Verify that your pet was created
• Some sample Swagger UI doc sites
• Activity: Create a Swagger UI display with an OpenAPI spec document
• Activity: View local OpenAPI file in Swagger UI
• Configuring Swagger UI parameters
• Challenges with Swagger UI
• Troubleshooting issues with Swagger UI
• Embedding Swagger UI within an existing site
• Key terms

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.

The endpoints are grouped as follows:

• pet
• store
• user.

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:

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.

   

   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.

   

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

   

   Important: The Petstore is a functioning API, and you have actually created a pet. You now need to take responsibility for your pet and begin feeding and caring for it! All joking aside, most users don’t realize they’re playing with real data when they execute responses in an API (especially when using their own API key). This test data may be something you have to wipe clean when you transition from exploring and learning about the API to eventually using the API for production use.

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.

Smart technical documentation with easy content reuse.

All-in-one platform to create, share, and manage your documentation

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:

• Reverb
• VocaDB
• IBM Watson IoT Admin REST APIs
• The Movie Database API

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.

First, you’ll make sure you can view Swagger locally. Then you’ll switch the Petstore OpenAPI document URL with an OpenWeatherMap OpenAPI document URL.

1. Go to the Swagger UI GitHub project.

2. Click Code, 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. (If desired, you can drag the dist folder out of the swagger-ui-master folder so that it stands alone.)

3. In your Chrome browser, press Cmd+O (Mac) or Ctrl+O (Windows), browse to the dist folder, and select the index.html file,

   You should see the Petstore Swagger content. Now you’ll customize the OpenAPI spec file with another file.

4. Inside your dist folder, open swagger-initializer.js in a text editor such as Sublime Text.

5. Look for the following code:

   url: "https://petstore.swagger.io/v2/swagger.json",
   

6. Change the url value to an online web URL to your Swagger file. For example: https://idratherbewriting.com/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml. Then save the file.

   If the url reference isn’t to an online URL (but rather to a local file), Swagger UI will create an CORS (cross-origin resource sharing) error. To view Swagger UI with a local OpenAPI file, you can run a simple Python server locally to simulate a web server (this requires you to install Python).

7. Refresh the index.html file in your Chrome browser. The content should show the OpenWeatherMap API content instead of Swagger Petstore content.

   When you’re ready to publish your Swagger UI file, you just upload the dist folder (or whatever you want to call it) 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/.

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

Activity: View local OpenAPI file in Swagger UI

In order to view a local OpenAPI file (rather than an OpenAPI file hosted on a web server), you’ll need to run an HTTP server on your computer. This is because CORS (cross-origin resource sharing) security restrictions in Chrome will block Swagger UI from running. Swagger UI needs to load on a web server to fulfill the security requirements.

You can create a local web server running on your computer through Python’s SimpleHTTPServer module. Mac has a system version of Python installed by default, but Windows computers will need to install Python.

Windows: Run the Python simple HTTP server

1. Download and install Python 3x.

   When you install Python, be sure to select the check box that says “Add Python 3.7 to PATH.” This check box isn’t selected by default. If you don’t select it, your command prompt won’t recognize the word “python”.

   

2. After installing Python, close your command prompt and reopen it.

3. In your command prompt, browse to the Swagger UI dist directory.

   To browse in the Windows command prompt, type cd <folder name> to move into the folder. Type cd .. to move up a directory. Type dir to see a list of the current directory’s contents.

   If you’re having trouble locating the dist directory in the command prompt, try this trick: type cd, press the spacebar, and then drag the dist folder directly into the command prompt. The path will be printed automatically.

4. After you’ve navigated into the dist folder, launch the server:

   python3 -m http.server
   

   If this command doesn’t work, try it without the 3:

   python -m http.server
   

   The server starts:

   Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
   

   (If your Command Prompt doesn’t recognize python, then you probably need to add Python to your PATH. Instructions for doing that are outside the scope of this tutorial.)

5. Go to http://localhost:8000/ in your address bar. This address lets you view the local web server.

   By default, web servers default to the index.html file in the directory, so it will show the Swagger UI file automatically. If the browser doesn’t direct to index.html, add it manually: http://localhost:8000/index.html.

   To stop the server, press Ctrl+C in your command prompt. If you closed your Command Prompt before stopping the service, type ps, find the process ID, then type kill -9 <process ID>.

Mac: Run the Python simple HTTP server

1. In your terminal, browse to the Swagger UI dist directory.

   To browse in your terminal, type cd <folder name> to move into the folder. Type cd .. to move up a directory. Type ls to see a list of the current directory’s contents.

   If you’re having trouble locating the dist directory in the command prompt, try this trick: type cd, press the spacebar, and then drag the dist folder directly into the command prompt. The path will be printed automatically.

2. Since Mac already has Python, you can just run the following in your terminal to launch simple server:

   python -m http.server
   

   If this command doesn’t work, try it with the 3 in case you already have Python3 installed:

   python3 -m http.server
   

   The server starts:

   Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
   

3. Go to http://localhost:8000/ in your address bar. This address lets you view the local web server.

   By default, web servers default to the index.html file in the directory, so it will show the Swagger UI file automatically. If the browser doesn’t direct to index.html, add it manually: http://localhost:8000/index.html.

   To stop the server, press Ctrl+C in your command prompt. If you closed your Command Prompt before stopping the service, type ps, find the process ID, then type kill -9 <process ID>.

For more details on using the Python simple server, see How do you set up a local testing server? for more details.

Customize the OpenAPI file

By default, SwaggerUI has the Petstore OpenAPI document configured in the url parameter in the index.html file. You need to swap in your local file instead.

1. Download the this OpenAPI document (right-click the link and save the YAML file to your desktop.).

2. Drag your OpenAPI specification file, openapi_openweathermap.yml, into 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
   │   └── openapi_openweathermap.yml
   

3. Inside your dist folder, open swagger-initializer.js in a text editor such as Sublime Text.

4. Look for the following code:

   url: "http://petstore.swagger.io/v2/swagger.json",
   

5. 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",
   

6. View the index.html file locally in your browser using the Python simple server. For example, go to http://0.0.0.0:8000/ or http://0.0.0.0:8000/index.html.

   If you go to the file path, such as file:///Users/tomjohnson/Downloads/dist/index.html, you might see a message that says “Failed to load API definition” note in the JavaScript Console that says “URL scheme must be “http” or “https” for CORS request.” The SimpleServer simulates this http or https.

7. To stop the Python simpler server, press Ctrl+C in your terminal or command prompt.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.