chapter five

5 Documenting REST APIs with OpenAPI

 

This chapter covers

  • Using JSON Schema to create validation models for JSON documents
  • Describing REST APIs with the OpenAPI documentation standard
  • Modelling the payloads for API requests and responses
  • Creating reusable schemas in OpenAPI specifications

In this chapter, you’ll learn to document APIs using the OpenAPI. OpenAPI is the most popular standard for describing RESTful APIs, and it has a rich ecosystem of tools for testing, validating, and visualizing APIs. Most programming languages have libraries that support OpenAPI specifications, and in chapter 6 you’ll learn to use OpenAPI-compatible libraries from the Python ecosystem.

OpenAPI uses JSON Schema to describe an API’s structure and models, so we start by providing an overview of how JSON Schema works. JSON Schema is a specification for defining the structure of a JSON document, including the types and formats of the values within the document.

5.1 Using JSON Schema to model data

5.2 Anatomy of an OpenAPI specification

5.3 Documenting the API endpoints

5.4 Documenting URL query parameters

5.5 Documenting request payloads

5.6 Refactoring schema definitions to avoid repetition

5.7 Documenting API responses

5.8 Creating generic responses

5.9 Defining the authentication scheme of the API

5.10 Summary