Design and Build Great Web APIs

Creating Your OpenAPI Document with SwaggerHub

The “engineering” document we’ll use to prototype our API is the OpenAPI Specification. The advantage of OAS documents are that they’re easy to create and edit. There are also several supporting tools that can read OAS documents and generate things like server-side sample code, example API client applications, and human-readable documentation. These are all great shortcuts or prototypes that we can use to validate our design before committing expensive resources to building the production version of our API.

OAS documents have a well-defined structure. An OAS file includes three main sections at the top level:

• The info section holds such information as the title, a brief description, and some additional ...