How To Document REST APIs With OpenAPI (AKA Swagger)

Create first-class documentation for your APIs with OpenAPI

If you’re a developer, you’ve probably worked more than once with a REST API. If you have, you’ll probably know how painful is to work with a badly documented (or even worse, non-documented) API. For this reason, when it’s us who is designing the API, it’s very important to document it well. That way, you’ll make life easier for the developers who want to work with it and for your future self.

One of the most popular standards for documenting REST APIs is OpenAPI, often called Swagger, despite that also being the name of the tools you use to create and view those documents. An OpenAPI document is written in JSON or YAML and describes how to use the endpoints your API is exposing, together with other details like the authentication mechanisms. From this document, a user-friendly HTML documentation can be generated, as well as client and server stubs in a variety of programming languages and frameworks.

Best of all, this can all be done for free. Today I’m going to show you how to document a dummy API for a books library, using OpenAPI in its YAML flavor. Our library API will just offer the basic CRUD operations:

• GET /books: get all the available books
• GET /books/{id}: get the details of a book with a specific ID
• GET /books/search: get all the books matching the search criteria (title, author…)
• POST /books: create a new book
• PUT /books/{id}: update the details of a book with a specific ID
• DELETE /books/{id}: delete a book with a specific ID

For the creation, modification, and deletion of a book, an API key will be required. Our book object will also be very simple, with the following properties:

• ID: unique identifier
• Title
• Author
• Year (optional)
• Pages (optional)
• TypeOfBook (optional): can be one of the following: novel, encyclopedia, comic, biography, and history.