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.
See how an OpenAPI document represents endpoint paths, methods, and request and response bodies. section 8.2.2
