Have you got the SWAG?

Disclaimer : As with most of the things I write, more for self reference rather than anything else.

If you have had anything to do with back-end REST API development, this might be for you. Unless all your backend work happens at the hackathons and you never open up those projects again. Or you are a vindictive Full Stack Developer who wants to keep everything to him/herself.

If you have had to don the role of a backend developer who has to break down requirements into manageable bite sized REST APIs, you realize that the process of communicating this to other stakeholders like the UI guy can be a PITA. Primarily cause they can’t remember stuff that easily due to their *creative pursuits*, or are too lazy to open up the excel sheet or e-mail you sent details all the endpoints which you built.

So here is where you need to have some Swag.

I am of course referring to the world’s most popular framework for APIs, http://swagger.io/

In a nutshell, they provide a framework for you to define and then develop the APIs, and once the API design has been captured in the swagger files, you can go ahead on your merry way and have your own personal API explorer.

Swagger is supported by many languages, but I am going to show the steps of getting started in NodeJS

The Swagger Project

Step 1:

$ npm install swagger -g

Installing swagger package globally

Step 2:

$ swagger project create test-api

Your terminal will look below

I scrolled down and selected express. After this swagger will create a scaffolding for you and then runs npm install (for you) in order to install the required dependencies

Project Structure Created

Now from the project folder, bring up your command line.

$ swagger project start

Note: The server will restart if you make any changes to the project.

Now you open another terminal and try out the api via a curl

curl http://localhost:10010/Hello?name=Steven+Gerrard

The Swagger Editor

Swagger comes built in with the swagger UI edtir, where you can design and model your API. This can be accessed by

$swagger project edit

This will open up a new tab in your default browser, which looks like this

Swagger Tools

To add swagger-tools to the project, enter the following command:

$ npm install swagger-tools --save

After that need add a few lines in app.js

var SwaggerUi = require(‘swagger-tools/middleware/swagger-ui’);

and

app.use(SwaggerUi(swaggerExpress.runner.swagger));

UPDATED app.js

Now if you navigate to your http://localhost:10010/docs/ and explore you will find this:

And, this URL http://localhost:10010/api-docs will serve the Swagger document (api/swagger/swagger.yaml).

You can try, test and play around with the endpoints in this UI.

Swagger.yaml

@ /api/swagger/swagger.yaml

Let’s do a deeper dive on the .yaml file which forms the backbone of API management which your project so seeks, precisely the paths section

paths:
  /hello:
    # binds a127 app logic to a route
    x-swagger-router-controller: hello_world
    get:
      description: Returns 'Hello' to the caller
      # used as the method name of the controller
      operationId: hello
      parameters:
        - name: name
          in: query
          description: The name of the person to whom to say hello
          required: false
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/HelloWorldResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

This short piece of yaml is what we need to define our routes:

x-swagger-router-controller: This is the controller, the file we have in the/api/controllers/hello_world.js.

Then the http methods must be listed, in the example just a GET.

operationId: This refers to the function, in the controller, in charge of the business logic.

parameters: The list of required parameters are defined here. The parametername is the only one and you may see that it is in the path, it is not required and it is a string.

When it comes to the responses, Swagger shows its potential, we can format all the responses in definitions section and reuse them.

Another vital section of code:

consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json

On the top of the file it has defined what the routes consume and produce, it is the format of the request parameters and related response. Those rules are currently applying to all the paths defined in the file. It is also possible to customize these rules for a single path/http method by including these properties inside of it.

To add more APIs, you can start with editing swagger.yaml to first design it and then add the logic in /api/controller folder.

References:

• Swagger: Install Guide
• Swagger Tools: Swagger UI Middleware

P.S : Enormous respect for UI/UX peeps, my comments were more out of my own shortcoming. PEACE!

Thanks for taking time out of your busy day to read this. If you liked it, click the 💚 below so other people will see this here on Medium.

Please do subscribe for more!