Creating Our OpenAPI Document with SwaggerHub

The info section

The info section of the OAS file holds general information about the OpenAPI Specification, such as the version number of the specification (not the version of the implemented API, just the specification document), the title, and the description. It turns out that we supplied these values when the SwaggerHub Editor asked us to enter data in order to start the editing process. We can also add a comment block that contains some additional metadata about the specification, as shown in the following code:

A Mock Server, Too: We see another section appears in the document loaded into SwaggerHub—the servers section. The information there was supplied by SwaggerHub to support a mock server for this API definition. The word “mock” means “not authentic” or “artificial.” Mock API servers act like the real thing but are just fakes.

The components section

Another important section in an OAS document is the components section. Technically the components section is an optional section, but we use it all the time and consider it key to a well-formed OpenAPI Specification document. The components section holds content that’s referred to in other parts of the definition—mainly the paths section that we’ll deal with next. Several elements of an HTTP CRUD-style API are often repeated. Placing the definitions of those items in the components section once and then referring to them many times in the paths section is a good way to properly build our API definition. To start, add the following to the bottom of OAS document:

This declares the components section and several important subsections. The subsections are where we’ll place the shared definitions that we’ll use in the paths section.

Most of the interesting work of defining our API will happen in the components section. For now, let’s add a few things here to illustrate how the section can help us build solid API ...