sails.js - Swagger Sails JS

Question

Any idea of how to integrate swagger, swagger-ui with a sails js project?

Where can i found information about it, or about another way to comment an api generated with sails?

Thanks!

Answer 1

I was searching for a solution for this a little over a week ago, but I found the information scattered a bit. Here's how I integrated swagger and swagger-ui with my sails 0.11.x project.

1. Install sails-swagger

npm install --save sails-swagger

This provides a hook that will dynamically generate the swagger document. Unfortunately, it's only compatible with sails 0.12.x (which is an rc at the time of this post). So, to get it working with 0.11.x you have to extend SwaggerController and overwrite the hook's name in config/installedHooks.js (issue reference)

api/controllers/SwaggerController.js

'use strict';

/**
 * This is a temp fix while one sails 11.x
 * @see https://github.com/tjwebb/sails-swagger/issues/3
 */
var _ = require('lodash');
var _super = require('sails-swagger/dist/api/controllers/SwaggerController');

_.merge(exports, _super);
_.merge(exports, {
  _config: {
    actions: false,
    shortcuts: false,
    rest: false
  }
});

config/installedHooks.js

'use strict';

/**
 * This is a temp fix while one sails 11.x
 * @see https://github.com/tjwebb/sails-swagger/issues/3
 */
module.exports.installedHooks = {
  'sails-swagger': {
    'name': 'swagger'
  }
};

Lastly, provide the hook's configuration per the docs

config/swagger.js

'use strict';

module.exports.swagger = {
  /**
   * require() the package.json file for your Sails app.
   */
  pkg: require('../package')
};

2. Install swagger-ui

npm install --save-dev swagger-ui@2

There are a few ways to handle this. You can use the vanilla swagger-ui module and add everything in its dist to your build process. But I chose to copy it into my project because I intend to customize the interface a bit.

mkdir assets/docs
cp -r node_modules/swagger-ui/dist/* assets/docs/

NOTE (3/26/2017): swagger-ui v3.x has been re-built using React (yay!), but easily integrating it with sails is not obvious at the moment.

3. Configure swagger-ui

Lastly, you need to point swagger-ui to your dynamically generated swagger doc. The default route for the swagger doc is /swagger/doc, so you can set it explicitly in the swagger-ui configuration.

assets/docs/index.html

<script type="text/javascript">
    $(function () {
      var url = '/swagger/doc';

      // Pre load translate...
      if(window.SwaggerTranslator) {
        window.SwaggerTranslator.translate();
      }
      window.swaggerUi = new SwaggerUi({
        url: url,
        // ...removed for brevity
</script>

4. Profit

Now you can navigate to /docs in your browser and see your beautiful documentation.