liveBook · Manning

OpenAPI specification

As explained in Microservices Patterns, Second Edition

A standard for describing HTTP APIs, including their operations, parameters, and schemas, in a machine-readable format.

A REST API needs a precise contract that clients and tools can use. The OpenAPI specification is an interface definition language (IDL) for describing that contract in a machine-readable document. section 8.2.2 section 8.4

An OpenAPI document describes endpoints, HTTP methods, parameters, request and response bodies, authentication mechanisms, and other metadata. It defines body structures using a variant of JSON Schema. section 8.2.2

Figure 8.5 An OpenAPI document describes a REST APIs endpoints including URL paths, HTTP methods, request and response bodies, and so on.
rest open api doc

The document describes API endpoints, including paths, methods, and request and response bodies. section 8.2.2

Tools can use the contract to generate client SDKs, server stubs, interactive documentation, and automated tests. It also supports API design and governance. section 8.2.2

A document can be handwritten or generated from code annotations and metadata. Generation reduces manual effort and helps keep the contract aligned with the implementation as a service evolves. Code generation is convenient for clients, but generated data transfer objects can unnecessarily couple a client at design time to the entire API. section 8.2.2 section 8.4

Generating a contract from a service

A Spring Boot service can use SpringDoc OpenAPI to generate an OpenAPI document from its controller classes and annotations. section 8.2.2

How Microservices Patterns, Second Edition covers it

How deep it goes
Describes contract fields, generation options, and tool uses without detailing document syntax.
Examples
Uses a Spring Boot service with controller annotations and SpringDoc OpenAPI to illustrate document generation.
What you can do after
Apply it via SpringDoc OpenAPI to generate a contract from Spring Boot controllers and annotations.
How it connects
Connects REST APIs to interface definition languages, JSON Schema, code generation, and API governance.

Also explained in

Compare how 14 books explain OpenAPI specification →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.