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 SwaggerUI and Netlify.com
In this chapter we’re going to take our OpenAPI definition and turn it into online documentation. Before hosting it online we’ll be adding some human touches such as the API metadata, rich text description and operation tags. These touches will make it a lot easier to consume by our users.
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 explaining the API from one person to another. In addition we’re also lacking some critical information that consumers require. Critical information such as the license of the API (are they allowed to consume it?) and contact information if they need to reach out. We’ll be adding this metadata to the definition under the info section.
Metadata is the data of the data, which is such a fun term to use. In our context it’s the data about the API definition, ie: all the necessary data that isn’t related to the mechanics of the API.