Thursday 4 April 2019

apidoc vs swagger for node app

While developing node services, we might need to expose our Api documents based on requirement. In that case we think of picking right documentation tool because there are many 3rd parties tools available for it. I have created sample POC by using 2 popular documentation tools
a. Swagger and
b. Apidocjs

Here is my finding regarding both:

  • Popularity: By comparing stats,  swagger-ui is more popular then apidocjs.
  • Consistency: If we already using swagger for our Dotnetcore service, then implementing swagger tool will consist more from Info and UI prospective.
  • Implementation complexity: apidocjs and swagger both required documentation content on implemented method as customize comment data. In addition they allow to write documentation data in separate resource file as .js and .json. If we already have swagger.json created by DotnetCore we can reuse more than 80% specification.
  •  Maintenance: For apidocjs will have to modify documentation for each affected method/endpoints if service changed. In swagger we can limit changes. But by implementing apidocjs we can isolate the layer.
  • Other benefits: Because swagger use plain .json that could be parsed through programing language, thus we can get advantage of various other 3rd parties in order to create http client and more. 
  • Future: Due to popularity of swagger, apidocjs provide information about apidoc-swagger converter so we can switch apidoc to swagger anytime.

Steps of using Swagger in to node app

1. Install following packages in your node app by running cmd commands:
npm install swagger-ui-express --save-dev
npm install window --save-dev

2. Add following snippet in app.ts
app.use('/images', express.static(__dirname + '/Images'));

//Use Swagger documentation
const Window = require('window');
var swaggerUi = require('swagger-ui-express'),
    swaggerDocument = require('./src/app/swagger');//When swagger.json available in app

const { document } = new Window();
var swaggerUi = require('swagger-ui-express');
const swaggerOption = {
    customCss: `.swagger-ui .topbar {
              background-color: #007298;
              }
              .topbar-wrapper span {
              visibility: hidden;
              }
              .topbar-wrapper img {
              content: url('../images/logo.png');
              width: 100px;
              height: 30px;
              }`,
    //swaggerUrl: '//www.dotnetapi.com/v1/swagger.json'), // When we need to add json from URL
    swaggerOptions: {
        defaultModelExpandDepth: 0,
        defaultModelsExpandDepth: -1,
        supportedSubmitMethods: ["patch"],
        validatorUrl: null,
        defaultModelRendering: [],
        deepLinking: false,
        onComplete: function (swaggerApi, swaggerUi) {
            document.title = 'Api Docs';
        },
    }
};
app.use('/api_docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, swaggerOption));