OpenAPI 3.0 documentation for Node.js REST API
Introduction
In this article, we implement OpenAPI 3.0 documentation for the existing REST API.
Use this link to clone the Library API which I use throughout this article (optional).
- Part 1 : explain how to create OpenAPI documentation for the Library API.
- Part 2 : explain how to integrate the specification with Library API.
Part 1: Create OpenAPI documentation
These are the steps we can follow to implement OpenAPI 3.0 documentation.
Identification of endpoints
First, we identify the endpoints of the Library API. In addition to that, we have to identify Request bodies for each endpoint and Response bodies for each response status.
The endpoints of the Library API as follows.
- Add a description for a book | POST /library/book/
2. Get details of a book by ISBN | GET /library/book/:isbn
- Request parameter of “isbn”.
- The response body is the same as the request body of endpoint 1.
3. Update description of a book by ISBN | PUT /library/book/
- The response body is the same as the response body of endpoint 1.
4. Delete description of a book by ISBN | DELETE /library/book/:isbn
- Request parameter of “isbn”.
- The response body is the same as the response body of endpoint 1.
Add information of the API
Let’s create a YAML file and name it “openapi.yaml”. As the first part of the documentation, we add the following code to your YAML file.
Note that you also can use JSON format to create OpenAPI documentation.
As you can see the “server” field explains the server information and the “info” field explain the API information.
Add components
Before documenting the endpoints we have to identify the components. We can document request and response bodies as components. This will help us to reuse the code for response and request body fields. Book and message are Identified as components using request and response bodies.
Let’s add the following code to end the YAML file.
We have to use schemas to define objects. Schemas include the following subfields.
- The “type” field is used to define the component types such as “object”, “string”, “integer”, etc.
- The “properties” field is used to describe the objects.
- The “required” field is used to identify the mandatory attributes of an object.
- The “example” is used to define an example object.
Note that the Book schema contains some fields which did not identify as required fields. Why?
Because POST endpoint request body contain all 5 fields of schema while GET endpoint status 200 response only contain “isbn” and “description” fields. To reuse the same schema for both situations I made this change.
Add paths
We put the following code to the end of the YAML file.
- The “response” field is used to describe the contents for each response status. Use this link to refer to the HTTP response status code.
- The first line after the “content” field is used to describe the media type. For the Library API, all the media types are “application/json”. Use this link to refer to more details about IANA media types.
- The “parameters” field is used to define the parameters. “in” subfields use to define parameter types for each parameter name. For the Library API, all the parameter types are “query”.
- “$ref” is used to add references to the component schemas we identified before.
Now we finished the creation of OpenAPI documentation. Let’s move to the documentation generation part.
Part 2: Integrate the documentation
- Install swagger-ui-express and yaml.js modules using the command “npm i swagger-ui-express yaml.js”
- Add the following lines to the index.js file and restart the server.
- Go to the URL (http:///<host>/<port>/api-docs) where host and port are “localhost” and “8000” for the Library API.
The resulting UI looks like this.
Conclusion
This article only explained the basic steps that can follow to implement OpenAPI documentation. You can refer more about the OpenAPI using this official link.
The complete code of the Library API with the YAML file is included in this link.
