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.
First, let’s clarify a few terms:
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 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 endpoints are grouped into three tags:
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 demo purposes. There isn’t any real logic authorizing those requests, so you can simply close the Authorization modal.
Now let’s make a request:
Click Try it out.
After you click Try it out, the example value in the Request Body field becomes editable.
idvalue to a random integer, such as
193844. Change the second
namevalue to something you’d recognize (your pet’s name).
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.)
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.
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.
You can also follow instructions for working with Swagger UI here in the Swagger.io docs.
To integrate your OpenAPI spec into Swagger UI:
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.
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.
Look for the following code:
url value from
http://petstore.swagger.io/v2/swagger.json to the following:
Save the file.
Drag the openapi_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
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.
As you explore Swagger UI, you may notice a few limitations with the approach:
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 more tools, see Swagger Tools.
68/94 pages complete. Only 26 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson