Swagger Sails JS [英] Swagger Sails JS

问题描述

知道如何将 swagger、swagger-ui 与 sails js 项目集成在一起吗?

我在哪里可以找到有关它的信息，或者可以通过另一种方式来评论用风帆生成的 api?

谢谢！

解决方案

一周前我正在寻找解决方案，但我发现信息有点分散.下面是我如何将 swagger 和 swagger-ui 与我的风帆 0.11.x 项目集成.

1.安装sails-swagger

npm install --savesails-swagger

这提供了一个可以动态生成 swagger 文档的钩子.不幸的是，它只与sails 0.12.x 兼容(在这篇文章中它是一个rc).因此，要使其与 0.11.x 一起使用，您必须扩展 SwaggerController 并在 config/installedHooks.js (

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!

解决方案

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.

这篇关于Swagger Sails JS的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！