What is Swagger?
Swagger is an open-source tool that allows you to describe the structure of your APIs so that machines can read them. Why is it so great? Well, by reading your API’s structure, it can automatically build beautiful and interactive API documentation. It also helps in testing the API’s endpoints.
This project is available here.
In this blog, we will document 5 RESTful API endpoints using swagger. These endpoints are described below:
|/api/fruits||GET||Returns all fruits|
|/api/fruits/:_id||GET||Returns a single fruit|
|/api/fruits||POST||Add a fruit|
|/api/fruits/:_id||PUT||Update a Fruit|
|/api/fruits/:_id||DELETE||Delete a Fruit|
It becomes really difficult for new employees to understand RESTFUL API documentation written in plain text by some other employee. Thus motivating me to do this project.
My goal with this project is to implement a frontend based API documentation which is easily understandable by everyone and as a result, the API testing becomes easy and efficient.
REST: Representational state transfer (a software architectural style that defines a set of constraints to be used for creating Web services).
Schema: A schema defines the structure of the document, default values, validators, etc.
YAML: It stands for YAML Ain’t Markup Language, a recursive acronym, to distinguish its purpose as data-oriented, rather than document markup.
- Basic programming fundamentals are a must
Step by Step Tutorial
1. This project uses MongoDB, so the first step is to create a fruits schema as defined below
I am using only a single property (i.e name) so that the project remains short and informative.
2. The second step for API documentation is to generate the swagger specification
The swagger specification is generated inside the server.js file with the help of an npm package namely swagger-jsdoc .
After generating the swagger specification we have to set up and serve it with swagger-ui-express.
This is the server.js file below:
Let us understand the code block by block, in order to get a better understanding of swagger.
The first block includes the requiring of the npm packages so that these packages can be used inside our application.
The second block includes the definition of swagger options which are automatically converted into swagger docs(swagger specification) with the help of swagger-jsdoc package.
The swagger options also consist of two parts: swagger definition and APIs
– swagger definition: The info part contains the title, description, and the server on which the app will be running. The components part consist of all other things like various schemas used in the project (fruits in our case)
–APIs: This is an array of paths of different APIs.
After this, serve the swagger specification at /api-docs endpoint.
After this run the server in order to check if swagger is successfully set-up or not, you should see something like this:
3. The third and final step is to create the routes and update the route handlers(the most important step towards interactive API documentation)
swagger-jsdoc uses JSDoc-type comments to generate the Swagger specification. So, add such comments, in YAML, to the route handlers that describe their functionality
This is pretty much self explanatory. We have an
/api/fruitsendpoint that returns two possible responses 200(successful) and 500(server error) to our GET request (you can add more like 401 error for unauthorized access)
$ref is used to refer to the response schema (defined in the components sections while generating swagger specs.) .
Similarly add such comments for other RESTful API’s also. Refer the code below :
With this step, our coding part is complete, so now in order to run and test it, Run the command node server.js and visit localhost:3000/api-docs to view the API documentation with Swagger UI. Here you can test your API’s by clicking on the respective API .
Learning Tools and Strategies
- Don’t write messy code, everything should be well understood. As a result, it will help you in debugging.
- Do a console.log() at each major step you feel is important or you feel maybe will throw some kind of error so that you are able to get the result of each major code-snippet.
- Another thing is to go through the documentation of swagger-jsdoc and swagger-ui-express thoroughly.
test, api, document, swagger, interactive api documentation
I prefer working in a quiet environment so that I am completely focused
Learning how to use swagger was a fun learning experience. It is an amazing tool that has makes the understanding and testing of API endpoints easy. A very common error that is expected while using swagger is the indentation of the comments, so be careful with that.
This project covers the documentation and testing of 5 basic RESTful API endpoints without authorizing and authenticating the user. How about a complete project that also includes authorization? Let me know your thought below on the comment section. Overall, I feel swagger is a great tool to do interactive documentation of your API’s endpoint. Refer to the documentation for some help.
This project is available here.