使用Redocly进行API文档编写：将OpenAPI规范转换为HTML

一. 背景与优势

在API开发过程中，清晰且全面的文档是确保无缝集成和高效采用的关键。OpenAPI规范（OAS）提供了一种标准化方式描述RESTful API，通过它可以定义端点、参数、响应以及认证方式。然而，原始YAML或JSON文件对开发者来说可能阅读不够直观。

将OpenAPI规范转换为HTML文档，可以为开发者提供更直观、易于浏览的文档形式，从而提升协作效率和API可用性。

1. 转换HTML文档的优势

清晰性与可访问性
HTML文档以交互式界面呈现API端点、请求参数和响应示例，使开发者能够快速理解和使用API。
用户友好性
支持折叠和搜索功能，开发者可快速定位所需端点，并进行测试调用。
团队协作与维护
HTML文档便于在团队内部共享，也便于持续更新和版本控制，提升协作效率。

二. 使用Redocly将OpenAPI规范转换为HTML

Redocly 是一个功能强大的工具，用于将OpenAPI规范渲染为交互式HTML文档。以下是具体操作步骤：

1. 安装Redocly CLI工具

确保本地已安装 Node.js 和 npm，然后运行以下命令安装Redocly CLI：

npm install -g @redocly/cli

安装完成后，可通过命令行使用 redocly 指令进行操作。

2. 创建OpenAPI规范文件

创建一个描述API端点、参数和响应的OpenAPI规范文件，支持YAML或JSON格式。例如，创建一个名为 swagger.yaml 的文件：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0
paths:
  /example:
    get:
      summary: 获取示例数据
      description: 返回示例数据的JSON对象
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, world!

这里示例展示了一个简单的GET端点，便于初学者快速理解规范结构。

3. 使用Redocly CLI生成HTML

在命令行中执行以下命令，将OpenAPI规范文件转换为HTML文档：

redocly build-docs swagger.yaml -o redoc-static.html

swagger.yaml 为你的OpenAPI规范文件路径。
redoc-static.html 为生成的HTML文件名称，可自定义。

执行后，将在本地生成一个完整的静态HTML文件，包含交互式API文档界面。

4. 预览与分享HTML文档

用浏览器打开生成的 redoc-static.html 文件，即可查看完整文档。HTML文档界面具有以下特点：

交互式折叠目录，便于快速浏览端点。
请求参数、响应示例和HTTP状态码直观展示。
支持本地共享或部署到静态站点服务器，例如GitHub Pages、Netlify等。

这种可视化文档特别适合开发团队、外部合作方或产品经理参考，提高沟通效率。

三. 拓展应用与实践建议

集成版本控制
将OpenAPI规范文件和生成的HTML文档纳入Git仓库，便于文档迭代与回滚。
结合持续集成
在CI/CD流程中，自动生成最新API文档，确保文档与实际API保持同步。
增强文档体验
Redocly还支持主题自定义、搜索功能以及API分组展示，可根据项目需求优化界面体验。
适用多语言团队
HTML文档无需安装任何额外工具即可浏览，非常适合跨团队和跨地域协作。

四. 总结

将OpenAPI规范转换为HTML文档是一种简单、高效且实用的方法，可以极大提升API文档的可读性、可访问性和团队协作效率。

使用Redocly工具：

安装CLI工具
准备OpenAPI规范文件
执行 build-docs 命令
打开HTML文档进行预览

几步即可完成从规范到交互式文档的转换，为你的API开发和推广提供便捷支持。

尝试使用Redocly，将OpenAPI规范快速转换为HTML文档，提升开发效率，让你的API文档更专业、更易于使用。

原文链接: https://www.tothenew.com/blog/api-documentation-with-redocly-converting-openapi-specs-to-html/