问题标签 [api-doc]

我必须记录我的 API。我必须使用其中任何一个Slate或Swagger。我想知道哪个有更多的选择，利弊，哪个更好。

我正在使用最新版本的 Swashbuckle 5.1.3 并注意到有一个新属性SwaggerResponse允许您记录每个响应代码的响应类型。例如：

（https://github.com/domaindrivendev/Swashbuckle/issues/175 < 可能有用）。

初始响应类记录得很好，但在它显示表格的更下方，"Response Messages"响应模型是空的（对于 400 Bad Request）。在屏幕上看不到记录了其他响应类型的任何地方。

我使用动态表单（定义为服务（！））来启用/禁用特定请求（POST/PUT/PATCH）的某些字段。我希望通过将选项传递给文档中所述的表单来自动显示在 ApiDoc 中。但它不起作用。我用这个：

但是通过 xdebug 我可以看到 $options['method'] 总是等于 'POST'，就像我没有指定“options”={“method”=“PUT”} 时一样。

我正在使用grape-swaggergem，但无法在 Swagger 中正确描述基于 Grape 的 API。使用：grape (0.11.0)和grape-swagger (0.10.1)

当我启用 Swagger json 列表时，我得到的输出列出了所有端点，但没有列出每个端点中包含的方法。

我的输出：

我还在 config.ru 中添加了 CORS 津贴，如下所示：

关于如何获取里面列出的每个端点的方法的任何线索？

我正在使用 Swagger 2.0 生成文档。在我的控制器类中，我有一些操作，例如：

为响应上述操作而生成的 Swagger 文档：

在这里，Swagger 文档没有说响应是Page<Employee>. 如何在 Swagger 的文档中获取泛型数据？

如果我有以下返回类型怎么办？

Swagger 操作参数和模型属性也是如此。

好的，所以我在使用 apidocjs 来解决它，然后在生产环境中实现它并且遇到以下问题：

以下是它正在查看的块注释（每个都在一个单独的文件中）：

我已经知道的：

这不会导致更新失败，apidoc 会按预期更新输出目录。

如果我在调用 apidoc 之前删除了输出目录，则没有警告。

如果没有要解析的文件，警告仍然会出现。

在寻找答案之后，我能找到的最多的是一个与我的问题相似的问题，除了提问者在他的 apidoc.json 中也有格式错误。话虽如此，该线程中的答案并不能真正满足我的要求（一个是在调用 apidoc 之前删除输出文件夹，另一个是如果您想保留历史记录，则不要删除输出文件夹，也许你有格式错误）。

来自更有经验的 apidocjs 用户的任何见解都会受到欢迎。

对不起文字墙

我们有一个 Python 项目，我们的文档目前分布在三个地方：我们有示例 Python 文件，我们有 Sphinx 文档（其中一些是从 IPython 笔记本生成的），我们有 IPython 笔记本。我们正在考虑将所有这些文档整合到一组 IPython 笔记本中。最终，我们希望通过将所有文档移动到一个地方并使用一个工具（IPython 笔记本），让我们的用户和开发人员的生活更轻松。而且，老实说，最大限度地减少维护文档所需的时间是这里的重中之重：所有开发人员都在空闲时间免费工作。

与 IPython 笔记本相比，Sphinx 的一大优势是 Sphinx 可以使用 apidoc 从代码中自动生成 API 文档。我的直觉是，应该可以通过编写一些遍历库的 python 文件的代码在 IPython 笔记本中复制这种行为，提取文档字符串以在笔记本中显示（包括渲染任何数学或图像以及文档字符串的相关部分（参数、返回值、注释等））。我的问题是：这样的工具是否已经存在？即一个可以遍历 Python 目录、提取文档字符串并将它们显示在 IPython 笔记本中的工具，最好使用漂亮的 HTML 格式？

我正在使用apidoc将我的 API 文档从 Github 中的平面文本文件移动到 Javadoc 注释。

因此，我已经有了想要用 javadoc 语法编写的 API 输出示例。我需要*在每行的开头添加一点而不是手动输入它们，因为它们很多。是否可以在 Eclipse 中做到这一点？我在任何地方都找不到它。

例子 ：

我想转

进入

我是节点的新手，

实现文档模块，我有一些测试文件，/lib其中包含示例中的文档注释。

我跑

./node_modules/apidoc/bin/apidoc -i lib / -o docs/apidoc

它响应 >info:Done

现在我的基本问题是，如何访问此文档？

http://localhost:8080/doc/index.html

正如这里建议的那样不起作用，我没有在我的主 js 文件上配置这个路径，

那么如何访问文档的索引？，在哪里配置呢？，干杯

我是 Sails.js 和 Node.js 的新手，在为我的应用程序创建文档时遇到问题。

这是我的步骤：

• 通过以下方式安装 apidoc： npm install apidoc -g
• 安装的 grunt 模块： npm install grunt-apidoc --save-dev
• 添加grunt.loadNpmTasks('grunt-apidoc');到底Gruntfile.js 部
• 创建grunt.initConfig文件并放置：

apidoc: { myapp: { src: "api/controllers/", dest: "apidoc/" } }

然后我尝试运行多个东西，但它们都没有生成我的 api 文档：

• 帆升降机
• 咕哝
• 咕噜默认
• 节点应用程序.js

如果我手动运行它，apidoc -i api/controllers/ -o apidoc/它就可以正常工作。

我究竟做错了什么？怎么做？