This chapter covers
- Adding metadata to our API definition
- Writing a description in Markdown
- Grouping operations together using tags
- Hosting our API documentation online using Swagger UI and Netlify.com
In this chapter we’re going to take our OpenAPI definition and turn it into online documentation (see figure 8.1). Before hosting it online, we’ll add some human touches, such as API metadata, rich text descriptions, and operation tags. These touches will make it a lot easier for our users to consume.
So far we’ve only been describing the bare essentials of the API, such as what operations exist and how to use them. This is the meat of the definition, but we’re lacking a softness that comes from one person explaining the API to another. In addition, we’re lacking some critical information that consumers require, such as the license of the API (are they allowed to consume it?) and contact information in case they need to reach out. We’ll be adding this metadata to the definition under the info section.
Metadata is the data about data, and it’s a fun term to use. In our context, it’s data about the API definition: useful data that isn’t directly related to the mechanics of the API.