Swagger Sails JS

Question

如何将 swagger ，swagger-ui与 sails js 项目整合在一起？

我在哪里可以找到有关它的信息，或关于用帆来评论api的其他方式？

谢谢！

Answer 1

一周前我正在寻找解决方案，但我发现信息有点散乱。这就是我如何将swagger和swagger-ui与我的风帆0.11.x项目结合起来。

1。安装sails-swagger

npm install --save sails-swagger

这提供了一个动态生成swagger文档的钩子。不幸的是，它仅与帆0.12.x兼容（这是本文发布时的rc）。因此，要使它与0.11.x一起工作，你必须扩展SwaggerController并覆盖config / installedHooks.js中的钩子名称（issue reference）

API /控制器/ 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
  }
});

配置/ 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'
  }
};

最后，根据文档提供钩子的配置

配置/ swagger.js

'use strict';

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

2。安装swagger-ui

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

有几种方法可以解决这个问题。您可以使用vanilla swagger-ui模块并将dist中的所有内容添加到您的构建过程中。但我选择将其复制到我的项目中，因为我打算稍微自定义界面。

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

  

注意（2017年3月26日）：swagger-ui v3.x已使用React重新构建（yay！），但目前并不容易将其与风帆集成。

3。配置swagger-ui

最后，您需要将swagger-ui指向动态生成的swagger文档。 swagger doc的默认路由是/swagger/doc，因此您可以在swagger-ui配置中明确设置它。

资产/文档/ 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。利润

现在，您可以在浏览器中导航到/docs并查看漂亮的文档。

Answer 2

我找到了使用swagger-ui的解决方案。我在资产 sails文件夹中创建了一个名为 docs 的文件夹，将 swagger-ui 内容放入其中，然后编辑 swagger.json 文件。然后，我做了帆升降机。文档现在可在http://ip_address:1337/docs中找到。我正在使用风帆v-0.11.0

Answer 3

在自动生成文档方面，您可以查看此库，因为我认为它可以更好地解决问题，只需从控制器和路由中自动生成swagger.json文件。

npm install sails-hook-swagger-generator --save

然后只需sails lift并检查 swagger 文件夹，您必须在运行sails lift

之前创建该文件夹

有关配置的更多信息，您可以查看仓库here

Answer 4

安装

$ npm install sails-swagger --save

配置

    // config/swagger.js
module.exports.swagger = {
  /**
   * require() the package.json file for your Sails app.
   */
  pkg: require('../package'),
  ui: {
    url: 'http://swagger.balderdash.io'
  }
};

安装和配置swagger后，您可以在/swagger/doc路径上找到文档输出。

Answer 5

安装：npm i @logisticinfotech/sails-hook-actions2-swagger 并在浏览器http://localhost:1337/swagger中打开。

只有那样，很酷。