Document your REST API with Swagger
By: Mohamed Lemine Baillahi
Tags: Documentation, Rest Api, API, Swagger

Programming wide world became more about services and microservices, building a REST API is sometimes a great solution to avoid having a monolith app, 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.