liveBook · Manning

OpenAPI document

As explained in Microservices Patterns, Second Edition

An OpenAPI document is a machine-readable description of an API's endpoints, methods, parameters, representations, authentication, and metadata.

An OpenAPI document is a machine-readable contract for a REST API. It describes endpoints, HTTP methods, parameters, request and response bodies, authentication, and other metadata. Body structures use a variant of JSON Schema. section 8.2.2

Use the document as a shared artifact for API design and governance:

  • Generate client SDKs, server stubs, interactive documentation, and automated tests from the contract. section 8.2.2
  • Handwrite the document or generate it from code annotations and metadata; generation can reduce manual effort and keep the contract aligned with the implementation. section 8.2.2

Spring Boot service

A service can use SpringDoc to generate an OpenAPI document from controller classes and annotations. 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

See how an OpenAPI document represents endpoint paths, methods, and request and response bodies. section 8.2.2

How Microservices Patterns, Second Edition covers it

How deep it goes
Specifies endpoints, methods, parameters, bodies, authentication, and metadata, with body structures defined using a JSON Schema variant.
Examples
Generates a service contract from Spring Boot controllers and annotations using SpringDoc.
What you can do after
Apply OpenAPI tooling to generate client SDKs, server stubs, interactive documentation, and automated tests.
How it connects
Connects REST APIs with interface definition languages, JSON Schema, and client SDK generation.

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.