Question

我正在研究sails js项目。如何为所有现有的api自动生成api文档（使用其JSON请求和响应）？

Answer 1

Swagger UI可用于创建专业的api文档。对于sas js和swagger集成，请参阅以下链接： -

https://www.npmjs.com/package/sails-swagger

Answer 2

我在所有的Sails项目中使用APIdoc。这就是我这样做的方式：

首先安装apidoc和rimraf作为开发代码：

npm install apidoc rimraf --save-dev

然后编辑你的包json并添加脚本来创建apidoc：

...package.json file
"scripts": {
    "docs": "rimraf public/docs && apidoc -i config/ -o public/docs",
    "start": "NODE_ENV=production node app.js"
  },
  "dependencies": {
... rest of package.json file

当然，公开/文档可以是您希望将文档放入的任何文件夹...我使用公开/文档

接下来，只需在config / routes.js中添加apidoc特定注释，或者如果您希望在控制器中写注释，请将上层脚本更改为运行-i / api / controllers而不是-i / config

我使用的一个额外技巧是直接使用sails提供文档，因此可以通过编辑.sailsrc文件在localhost：1337 / docs上使用，并添加：

{
  "generators": {
    "modules": {}
  },
  "hooks": {
  },
  "paths": {
    "public": "public" //name of the folder where all my public assets are (including docs)
  }
}

每当您想要新的文档副本时，只需运行：

npm run docs

您还可以通过在package.json内部的启动脚本内部甚至在config / bootstrap.js内添加文档生成来自动执行此操作。但是我发现在需要时手动调用文档会更好。它加快了提升过程。

编辑：忘记提及你也可以在package.json文件中传递apidoc配置：

...package.json file

  "main": "app.js",
  "repository": {
    "type": "git",
    "url": "repo url..."
  },
  "apidoc": {
    "title": "My documentation title",
    // you can use all other config options here: http://apidocjs.com/#configuration
  },
  "author": "some guy",
  "license": ""
}

...rest of package.json file

Answer 3

您是否尝试使用您在个性化操作中定义的响应结构生成API文档？根据我的经验，我能够做到这一点的唯一方法是在每个控制器中使用手写的注释。我能够强制使用超媒体响应的API文档，而不仅仅是每个控制器的基本模型。如果有另一种方法，请分享。

如何为现有的sails js项目自动生成apidoc？

3 个答案: