Documenting an API with OpenAPI

An OpenAPI document is a file, in JSON or YAML, that describes an HTTP API completely: every path, method, parameter, request body, response, and the shape of every type. The OpenAPI Specification defines the format. Its stated goal is to let both humans and computers understand the capabilities of a service without access to its source code.

For the booking service, that document is 8,038 bytes of JSON, and nobody wrote it by hand. A library builds it from the controllers at startup and serves it next to the API, together with a web page for browsing it.