OpenAPI interface specification
OpenAPI is a standard way of describing HTTP APIs. Today, let’s talk about its interface specification ( OpenAPI specification (Chinese version) )~
OpenAPI version number specification
The version number of OpenAPI is defined using the format of major.minor.patch, such as 3.1.2
- major: Specifies the major version
- minor: specifies the minor version
- patch: specifies the patch in the minor version
OpenAPI format specification
OpenAPI can use JSON or YAML format, and the fields are case-sensitive:
JSON example
YAML example
OpenAPI document structure specification
An OpenAPI document can be a single document or multiple documents, at the discretion of your team. In the latter case, the $ref keyword needs to be used in Reference Objects and Schema Objects.
As for the naming of the document, it is recommended to name it openapi.json or openapi.yaml.
OpenAPI data type specification
The data type of OpenAPI must conform to the specification of JSON Schema Specification Draft 2020-12
JSON Schema specification address: draft-bhutton-json-schema-00
OpenAPI Rich Text Format Specification
The description field of OpenAPI supports the CommonMark markdown format, so when using rich text in OpenAPI, the format must conform to the CommonMark markdown format.
OpenAPI object
Info Object
Metadata describing the API
Contact Object
API contact information
Server Object
API server object information
can be a server
Can also be multiple servers
Components Object
Reusable Component Objects for API
Paths Object
An object describing the URL of the API
Path Item Object
An object with operations available on a single path
Operation Object
An object for a single API operation on a path
External Documentation Object
expand external resources
Parameter Object
parameter object
Request Body Object
An object of a single request Body
Responses Object
The API returns the response object
Header Object
request header object
Knowledge expansion:
- Understanding Swagger and OpenAPI: Best Practices for API Design and Documentation
- OpenAPI Getting Started Guide