Swagger Examined (Part 1): How to document an API with incredible simplicity

Do you know what Swagger’s main characteristic is? It is its incredible simplicity: its capacity to easily and utterly describe how an API works, where it resides, what inputs it needs, and what results it produces.

It is this simplicity that helped Swagger make itself one of the most successful developmental tools available on the market.

It is the same need for efficiency that makes Swagger compliant REST services so invaluable when a new API is created.

In this article you will learn the basics on how to create a Swagger RESTful documentation based on another popular technology known as JSON.

So let’s start by learning about a great tool: the Swagger Editor

Using Swagger

There are several editing tools that can help you to create Swagger compliant APIs. One of them is the Swagger Editor, which you can use to create your API documentation. It is an open source tool that you can download, or use it online.

Figure 1 – Swagger Editor

Learning JSON

If you are looking for a good reference on JSON, you can consult the standard available here. Alternatively, you can also read the RFC 7159 that is available here. Both of them present a complete description of JSON, but they are very technical.

Alternatively, if you need a rookie’s site that will teach you JSON from scratch, you can go to W3SCHOOLS.

Document description

The Swagger standard defines the structure of the JSON file that describes a RESTful web service.

Here below is a simplified description of the main sections.

Document sections

The main sections that you need to understand are: the API declaration, the paths and the definitions.

API declaration

The API declaration section describes the main aspects of an API, such as its title, version, where it is hosted, the schemes that it uses, and the MIME types it consumes and produces.

The required parts are:

1. Swagger version:  specifies the Swagger Specification version being used.
2. basePath: the root URL serving theAPI.
3. The apis or paths section: a list of the APIs exposed on this resource. There must be no more than one APIS object per path.

The consumes and produces sections list the MIME types the resource consumes and produces.

Additional information shown in the figure below, which is optional, includes the license, the host and the x-parameters. The x-parameters, such as x-response-strategy, are pairs of keys and values defined by you.

Figure 2 – API declaration

MIME types

The MIME types that can be consumed or produced are summarized in the table below. In our example we use a JSON type, but XML and XHTML are also other possible options.

Table 1 – MIME types

Paths

The path describes the different operations. The required parameters are:

1. The method required to invoke the operation. The possible values are:  GET, POST, HEAD, PUT, PATCH, DELETE, OPTIONS and TRACE.
2. Parameters: are the inputs to the operation. Each parameter must include its name and type. Other characteristics are optional.

Additional parameters shown in the below figure, which are optional, are:

• Produces: a list of MIME types produced. In this case JSON type.
• Responses: a description of the responses available in this operation.
• Path parameters: between curly brackets, they must be provided by the API call.

Figure 2: paths

Definitions

The definitions or data models section contains a list of data objects. Each data object can have several parameters.

The required parameters are:

1. Name: the name of the data object.
2. Properties: the fields that define the data object. Each property has a name and a type.

Figure 3 – definitions

Where to find more information

The best reference is the official Swagger page, which is available here.

Conclusion

The Swagger standard provides a great tool to document APIs. In this article you have learnt the main components of this documentation, namely API declaration, paths and definitions or data models.

In the next article of this series you will read about the general characteristics of Swagger, its core benefits and how DBSync uses it for your businesses.

If you want to learn more about this wonderful technology, consult the Swagger page. Even more, if you want to learn how we have applied Swagger to apps integration, visit our page.