Document your REST API with Swagger

Programming wide world became more about services and microservices, building a REST API is sometimes a great solution to have more flexibility in your developement process, so you build a complete frontend that calls a separated REST API which does the rest of the job related to data handling and storing, but most of times if you’re building the backend you’re doing that in a team and other members need to get description about every endpoint in your API, here comes the role of Swagger as one of the best way to do that, Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful web services.

Method 1 :

To do that we’ll start with the easiest way, Swagger bases on a main yaml file that we can preview either locally (this needs a previous installation of Swagger) or online (doesn’t need any little installation), it’s quite easy to go through the syntax so let’s get started.

Here we’ll choose to have Swagger tools installed locally to have the Swagger editor running locally, so install it with :

npm install swagger

Then go to your project and create a file under : “api/swagger/swagger.yaml” this will be our yaml file to set our configuration, it doesn’t matter what technology you used to build your API neither your runtime environment, but we need just to know about the endpoints and the data structure sent or/and received, so let’s take the configuration piece by piece

In the first line we specify the used swagger version then we start our API’s main description :

• description : to give what’s your API about mainly
• version : the version of this API, it’s exactly like when you’re dealing with package.json npm configuration file
• title : the title to show in the preview page
• license : here we’ve MIT license which means that it’s opensource
• url : a link to the license terms
• host : your API root url, here we’ve localhost with the port 4000
• basePath : this path will be used to map the different calls (these calls will be described below) to your services.

The second script part

• tags : here you define tags related to each endpoint; for example we defined here the tag “root” for the entry endpoint that will be tagged on the endpoint, you’ll understand it more better when we preview it just below
• schemas : to define what protocol to use in the call
• paths : finally here we define our endpoints backbone, so here we define the path to our endpoint, the response and the request object type (here it’s application/json), the responses with description, and if the request has any parameters we’ve to define them with their schemas.

Let’s define another endpoint that needs parameters in the body request

Simply here we define an endpoint under post method that receive an object parameter in the body, this object has two fields “login” and “password” both of them are strings, if everything goes ok then the response will be given under the status 200 otherwise with a bad typed user we get 405 sure with the server response description.

Now go to the root folder and type :

swagger project edit

That will open swagger editor to preview your “yaml ”file, it provides a live script interpretation so from now on you can edit your code directly in the swagger editor to preview it side by side

You can custom your responses, your paths as much as you can, take your coffee and type some code 😉☕👩‍💻

You can share your Swagger documentation by hosting your yaml file on SwaggerHub, and to get more deeper you can practice with the Swagger live editor from here.

Method 2 :

This method depends on your API environment like if it’s a nodejs API then you’ll need to have “swagger-ui-express” package in your project and if it’s a spring boot REST API then you’ll need “springfox-swagger2” package, in this article we’ll take as an example a simple nodejs REST API so let’s get started

Let’s create our nodejs REST API, create a workspace folder and name it (for example) “myapi ” then the root js file “index.js” and initialize the directory with npm :

• create the workspace directory :

mkdir myapi

• create the root js file ( you can do it with the command “touch index.js” on linux dest or just standardly)
• initialize the directory with npm (leave everything default) :

npm init

Then install “express” with :

npm install express

Now let’s create our services, the first one is the entry point that says “Welcome” at the root endpoint with GET method and the second one is a POST method that check if a user’s object is valid or not :

As you can notice at the line number 5 that we imported Swagger needed packages, so don’t forget to install them with :

npm install swagger-ui-express

Alright, let’s go now and start our swagger documentation, create a json file on your root folder and name it “swagger.json”, the syntax in this file gonna follow sure the json syntax and rules but with the same old keys as seens in “Method 1”

As you can see nothing changed exactly as seen in the first method but this time we put that logic in a json file instead of a yaml file.

Now, simply open you browser with http://localhost:4000/api-docs/ so preview your documentation that’s it

That’s it .. 😁😉 for more description about Swagger don’t hesitate to check the official documentation from here.

You can find both Method 1 and Method 2 to document your API source code from here : https://github.com/BLemine/Swagger_Medium_Article