Introducing OpenAPI and JSON Schema
The OpenAPI Specification, backed by the OpenAPI Initiative (https://www.openapis.org/), defines a formal language that both humans and computers can read to learn about the capabilities of a service without the following:
- Access to the service implementation code
- Separate documentation in another format (language)
- Analyzing the network traffic
The OpenAPI Specification was originally based on the Swagger Specification. OpenAPI can describe any API using the HTTP protocol, including RESTful APIs at any maturity level.
OpenAPI Specification documents can be written in JSON and YAML formats. The YAML syntax (https://yaml.org/) replaces a lot of the JSON punctuation with indentation; therefore, YAML tends to be more concise and easier to read for many humans. In this book, we will use the YAML format for all OpenAPI Specifications written manually (not generated by tools).
The two most important (and usually...
