Designing and Documenting a RESTful API Using Swagger

 

The prevalence of RESTful APIs is visible in a vast majority of web and mobile applications that we consume and — as API developers — that we code. They serve as a common interface that can be shared between web and mobile applications, and they allow us developers to reduce the number of codebases that we must maintain to support a wider range of applications. Given the impact of APIs in the industry, developers should take care to fully engage at every stage of the development lifecycle.

One of the most commonly overlooked steps in the development lifecycle is documentation. For me, it’s a task I inevitably put off as long as possible. Yet, it’s a critical piece of an application that, when done and done well, helps drive adoption. It would be a shame to invest hundreds or even thousands of hours into developing an API only to have potential users abandon it because they aren’t able to discover its capabilities quickly and easily.

This is where the beauty of Swagger comes in. By integrating your API specification with Swagger, you get the tools to design, build and document your API. This post will cover the Swagger tools available to design and document your API specification. I’ll save the build step using Swagger Codegen for a possible future post.

 

Why Swagger?

Swagger offers flexibility for developers on several levels.

 

Widely Adopted

Swagger provides a powerful framework of tools based on the Swagger Specification. This is an open-source specification that is the basis of the OpenAPI Specification (OAS). The Swagger Specification and suite of tools have become an industry standard for describing RESTful APIs and have been adopted by millions of developers and companies.

 

Programming Language Support

Swagger supports over 25 programming languages, so unless you’re coding in some eccentric language, Swagger probably supports your choice.

 

Feature-rich Framework

Swagger provides a complete framework of free and open-source tools that enable you to design, build and document your RESTful API quickly and efficiently.

 

Design With Swagger Editor

Swagger Editor is a browser-based tool that lets you quickly design your API using a straightforward YAML syntax. As you build out your API definition with the editor in the left pane, it’s rendered for you in the right pane, letting you immediately visualize your definition and easily identify errors.

 

Figure 1

Figure 1. Swagger Editor

 

Document With Swagger UI

Swagger UI is a feature-rich toolset that allows developers and API consumers to visualize and test the API without the need to code an application just to make the necessary web requests. It has become an industry standard, meaning consumers of your API are presented with a familiar interface. This familiarity translates into less time spent searching through your documentation, and more time getting to know your API and ultimately, hopefully, a higher adoption rate for your API!

 

Figure 2

Figure 2. Swagger UI

 

Summary

I’ve covered what Swagger is and why it’s beneficial to adopt. Now I’d like to take a closer look with a real-world example.

 

An Example Using JavaScript, Node.js, and Express

In a typical RESTful API project, you might design your API in a modular way that implements a /routes folder containing a single index.js file responsible for routing your API requests to the correct controller code.

 

Node App Without Swagger

 

/** ./server.js */
app.all('/api/v1/*', [require('./api/middlewares/validateRequest')]);
app.use('/', require('./api/routes'));

/** ./api/routes/index.js */
var router = require('express').Router();
var auth = require('../controllers/auth');
var customer = require('../controllers/customer');
var account = require('../controllers/account');
var admin = require('../controllers/admin');

// Public routes
router.post('/auth', auth.login);

// Must be authenticated to access these routes
router.get('/api/v1/customer', customer.getCustomers);
router.get('/api/v1/account', account.getAccounts);

// Must be authenticated AND properly authorized to access these routes
router.get('/api/v1/admin', admin.addUser);

Code Snippet 1. A Common RESTful API Routing Pattern

 

Note that the snippet above uses a middleware to handle authentication and authorization. With Swagger, you can continue to use your middlewares and Swagger won’t get in the way.

 

A Basic Node App Using Swagger

Using Swagger UI (for this example, we’re also using the Swagger-express-mw npm package), you can configure Swagger UI in your API server code and define your API specification in your swagger.yaml file.

 

/** ./server.js **/
var SwaggerExpress = require('swagger-express-mw');
var app = require('express')();
module.exports = app;

var config = {
    appRoot: __dirname
};

SwaggerExpress.create(config, function (err, swaggerExpress) {
    if (err) { throw err; }

    // install middleware
    swaggerExpress.register(app);

    app.use(swaggerExpress.runner.swaggerTools.swaggerUi());

    var port = process.env.PORT || 10011;
    app.listen(port);
});

Code Snippet 2. Defining Swagger UI in Your API Server

 

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"
  /swagger:
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
  HelloWorldResponse:
    required:
      - message
    properties:
      message:
        type: string

Code Snippet 3: swagger.yaml (note: some code removed for brevity)

 

Highlights of the swagger.yaml File

The following list highlights some of the key portions of the Swagger definition.

  • /hello:
    This definition specifies how users should be routed when they make a request to this endpoint.
  • x-swagger-router-controller: hello_world
    This line tells Swagger which code file acts as the controller for this endpoint.
  • get:
    This command defines the method being requested (GET, PUT, POST, etc.).
  • operationId: hello
    This command directs Swagger to the specific method in your controller to invoke for this endpoint.
  • parameters:
    This section defines the parameters of your endpoint. They can be defined as path, query, header, formData, or body.
  • definitions:
    This section defines the structure of objects used in responses or as parameters.

 

Why Should I Care?

The beauty of this process is that you don’t need a separate routing file and API spec definition file. Just define your API in swagger.yaml and the routing AND documentation are handled for you! To make defining your API even easier, you can use Swagger Editor to have a side-by-side view of your YAML definition and the resulting API documentation. It will instantly update to highlight any syntax or definition errors.

 

Figure 3

Figure 3. Quickly Identify Errors in Your API Definition Using Swagger Editor

 

Limitations of Swagger

The Swagger community has done a great job of putting together an excellent framework that just works well. I haven’t found many limitations in my experience with Swagger, but it does have a few:

  1. The Swagger specification doesn’t support nullable data types. The consequence of this is any fields you define as nullable won’t display in your model schema in Swagger UI. This limitation doesn’t prevent the use of nullable types, but it can create some confusion when you’re trying to discover your API definition.
  2. Swagger UI is pretty similar across implementations. I know, I just touted this as a benefit, and I believe it is. However, I can imagine a scenario in which a team would like to utilize the power of Swagger, but would like more control over the UI/UX. It isn’t impossible to do, but it requires quite a bit of re-engineering to do much more than update the skin of the UI.

 

Conclusion

Get out there and try Swagger! You’ll be up and running with very little effort, and building your RESTful API, along with its supporting documentation, much more consistently and efficiently.

 

Additional Resources

 

The following two tabs change content below.

Manny Merino

Manny joined Piraeus in September 2007 and is currently a Senior Solutions Architect at Beyondsoft. He has experience developing solutions using the Microsoft full stack of development tools as well as open-source JavaScript technologies. Contact Manny at manny.merino@us.beyondsoft.com.

Latest posts by Manny Merino (see all)

Share
This

Post a comment