Designing APIs with Swagger and OpenAPI

5 Describing API responses

This chapter covers

• Learning about JSON Schema and how to describe data
• Describing the 200 response of GET /reviews
• Adding a response definition to our FarmStall API

In this chapter we’re going to describe a simple HTTP response with OpenAPI and add it to our FarmStall API definition. We’ll look at the components of an HTTP response, comprising three parts: a status code, a set of headers, and an optional body. We’re going to focus on the status code and body for now (see figure 5.1). Headers will be covered incrementally throughout the next chapters.

Figure 5.1 Where we are

Describing response bodies is an important ...