Designing & Viewing APIs using Swagger Specification (OpenAPI)
This post helps form a good understanding on what Swagger Specification is and how to use it to your benefit in API design.
Topics covered in this post
- How to Design APIs using Swagger (OpenAPI) Specification.
- How to View a Swagger Specification File in VS Code Editor.
- How to Insert a Swagger Specification File in Atlassian’s Confluence wiki post.
It’s a specification for machine-readable files that help with designing your APIs, as well as implementing, documenting, testing and visualizing. The current name of the specification is the OpenAPI Specification, but it was originally known as the Swagger Specification.
The Swagger Specification file helps with sharing the API structure with your team and with other teams easily. The following image shows a portion of a Specification file’s content.
To get started, I’ll be using the online Swagger editor found here. The editor is pre-populated with a pet store example by default. The pet store example can be used as a reference before overriding it with your own APIs.
The following image shows a screenshot of the online editor, where the left side displays the content of the Specification file and the right side shows the UI preview of that Specification file.
Additionally, there are a few useful features offered by this Swagger editor, which are:
1. Importing, Exporting and Converting the Specification File
The APIs’ information all exists within a single specification file. This file is either a YAML file or a JSON file.Using the provided editor, you can always switch between the two file types based on your preference. The editor also allows you to import any external specification file or export the one you’re working on. The following image shows where to find those options.
2. Generating Servers (Stubs) & Clients
The editor also allows you to generate a server stub in a number of server-side languages and frameworks, such as Spring. The server stub is basically a starting point for implementing the APIs clarified in the specification file. Additionally, you can generate a client in a number of client-side languages that will consume your APIs. The following image shows the two generate options highlighted using red rectangles.
So, what about the content of the specification file?
To have a better understanding of the file’s content, we can divide the file into 4 sections. The file type I will be going with is YAML for ease of use as it depends on the indentation rather than JSON object structure but feel free to use whichever of the two you like.
The 4 sections of the file content are explained as the following:
Section 1: General Information of your APIs
This includes APIs’ version, title, host, base path, schemes, tags and other general information. The tags are the categories shown in the preview that allows you to group a number of APIs under it. The following image is a screenshot of this section.
This following image shows the tags, highlighted in red rectangles, in the UI preview side.
Section 2: APIs in Detail
This section contains a breakdown of each API you want to include in the specification file. This is done after the paths property in correct indentation.
Using the pet store example to understand the structure and content is a good idea at this point. You can gradually replace the pet store example with your own APIs and see how it looks in the UI preview section on the right.
The APIs details generally include the URL, the HTTP verb, the tag it belongs under, the description, the parameters, the response details and other additional information. The following image is a screenshot of this section.
Section 3: Security Definitions
This section may be needed for some of the APIs as the “Try it out” feature shown in the UI preview requires such information to be clarified if API requires any type of authentication to achieve a successful request and response. The following image is a screenshot of this section.
Section 4: Details of Models
In this section, payload structure is defined for all the APIs in the specification file. The definition name will then be used in Section 2. The following image is a screenshot of this section.
This following image is how the model definition can be used in Section 2 for payloads (response or body).
- Install the “Swagger Viewer” extension.
- Simply open your Swagger Specification file.
- Click command + SHIFT + p (for Mac).
- Type in “Preview Swagger” and a preview of your Swagger Specification will open on the side as shown in the following image.
- Go to “Insert” when you are in editing mode of a page.
- Choose “Other macros”.
- Type in “Swagger” and choose “Open API (Swagger) Viewer”.
- Click “Insert”.
- Then add your Specification file content to the Viewer block and save/preview to view the specification of your APIs.
The following image shows how the Specification file looks in edit mode.
This next image shows how the Specification file looks in preview/saved mode.
