是否有任何工具可以从 JSON 或 Open API 自动创建类似 wiki 的 REST API 文档？

Question

我有多项服务，每一项服务都通过 REST API 和 ASP.NET Core Web API 公开。我使用 Swashbuckle for ASP.NET Core 工具，以便从我的控制器和 DTO 自动生成所有必要的文档，并在 SwaggerUI 中将其可视化。我发现这个工具真的很棒，我的模型上几乎没有注释，而且我的控制器已经提供了许多开箱即用的功能，例如用于尝试 REST API 端点的 UI 客户端。
但通过此解决方案，每个服务都有自己专用的 SwaggerUI 实例和 UI。 我想向我的客户提供一个带有导航菜单的类似 wiki 的文档，例如，他们可以在其中浏览有关我的服务公开的所有端点的部分，并且在每个页面上具有 SwaggerUI 提供的相同功能。

它可以通过创建我自己的 Web 应用程序来实现，但我想知道是否已经存在开箱即用的解决方案或某种可以简化此类集成的工具。 我尝试过 Slate，但我觉得我必须重新发明轮子，以便至少自动创建基本 API 文档，即控制器定义、响应定义和描述。有人有什么建议吗？

Answer 1

我最近在微服务架构中工作时遇到了这个问题，你是完全正确的。无需重新发明轮子。

在这种情况下我真的不能推荐Redocly的redoc。

查看 multiple-apis 示例。

Answer 2

Libris 是一个很棒的文档生成器。但是，它使用与 Open API 或 JSON 不同的语法。使用 Libris，您可以将结构化文档字符串嵌入到代码库中，这些文档字符串将被解析并自动转换为文档页面。

这是一个 JavaScript 示例。但是，它支持以任何受支持的语言构建的 REST API。

/*  @docs:
 *  @title: List Entities
 *  @description:
 *      List the ... entitites.
 *  @language: REST API
 *  @method: GET
 *  @endpoint: /list
 *  @header:
 *      @name: Authorization
 *      @description: Required to perform authentication using your API key.
 *      @required: true
 *  @parameter:
 *      @name: sort
 *      @type: string
 *      @description: Sort the entitity list.
 *      @enum:
 *          @value: "asc"
 *          @description: Sort the list by ascending order.
 *      @enum:
 *          @value: "desc"
 *          @description: Sort the list by descending order.
 *  @response: 
 *      @200: 
 *          @application/json: 
 *              @description: Successful request.
 *              @code: 
 *                  {
 *                      "has_more": false,
 *                      "data": [...]
 *                  }
 *              @attribute: 
 *                  @name: has_more
 *                  @type: boolean
 *                  @description: ...
 *              @attribute: 
 *                  @name: data
 *                  @type: Entity[]
 *                  @description: ...
 *                  @attributes_type: Entity
 *                  @attribute: 
 *                      @name: id
 *                      @type: string
 *                      @description: The id of the entity.
 *                  ...
 */
app.get('/list', (req, res) => {
  ...
});

有关实施 REST API 文档的更多信息可以在其文档页面上找到。