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

在OpenAPI规范转换为HTML文档，并展示具体的操作步骤。

OpenAPI规范到HTML转换的优势

将OpenAPI规范转换为HTML文档具有以下显著优势：

清晰性与可访问性

HTML文档以直观的方式呈现API端点、参数和响应信息，使开发者能够快速理解和使用API。
用户友好的格式

HTML文档支持交互式查看，便于开发者查阅和测试API功能。

使用Redocly将OpenAPI规范转换为HTML的步骤

以下是将OpenAPI规范转换为HTML文档的具体步骤：

1. 安装Redocly CLI工具

首先，需要安装Redocly命令行界面（CLI）工具。可以通过Node.js的包管理器npm来完成安装，运行以下命令：

npm install -g @redocly/cli

2. 创建OpenAPI规范文件

接下来，创建一个描述API端点、参数和响应的OpenAPI规范文件，可以是YAML或JSON格式。例如，创建一个名为[swagger](https://www.explinks.com/wiki/what-is-swagger/).yaml的文件，内容如下：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0
paths:
  /example:
    get:
      summary: 获取示例数据
      responses:
        '200':
          description: 成功

3. 使用Redocly CLI转换为HTML

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

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

此命令会生成一个名为redoc-static.html的HTML文件。

4. 预览生成的HTML文档

在浏览器中打开生成的redoc-static.html文件，即可查看API文档。文档以用户友好的格式展示了API端点、参数和响应信息，方便开发者查阅和使用。

结论

通过将OpenAPI规范转换为HTML文档，可以显著提升API文档的可读性和可访问性。使用Redocly这样的工具，整个转换过程变得简单高效，为开发团队节省了大量时间和精力。尝试使用Redocly工具，亲身体验从OpenAPI规范到HTML文档转换的便捷性，为您的API开发工作增添助力！

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