5 Producing a REST API specification
This chapter covers:
- Why the JSON Schema is useful for defining API specifications
- Learning the Swagger/OpenAPI specification
- Defining the specification for the payloads in the requests and responses of the API
- Using generic components to refactor our schemas and write better and more readable and maintainable API specifications
- Generating API specifications with code
In this chapter, we put together all the concepts and ideas that we developed in chapter 4in order to write the specification for the orders API using the Swagger/OpenAPI standard. To do this, we first provide an overview of what JSON Schema is. JSON Schema is a specification format that can be used to define the structure of a JSON document, including the types and formats of the values within the document. In this chapter, we explain how we can leverage the concepts and resources that JSON Schema provides in order to define better and more readable schemas.
Swagger/OpenAPI is the most popular standard for describing RESTful APIs, and it provides a rich ecosystem of tools that we can use to validate and visualize our specifications. Additionally, as we will see in chapter 6 Python has numerous libraries built around the concepts of Swagger/OpenAPI, and those libraries will help us leverage the OpenAPI specification for our REST APIs to improve our development process.