Redoc 开源项目教程

最新推荐文章于 2024-08-09 08:19:43 发布

顾涓轶

最新推荐文章于 2024-08-09 08:19:43 发布

阅读量413

点赞数 10

本文链接：https://blog.csdn.net/gitblog_01085/article/details/141048406

版权

Redoc 开源项目教程

redoc📘 OpenAPI/Swagger-generated API Reference Documentation项目地址:https://gitcode.com/gh_mirrors/re/redoc

1. 项目介绍

Redoc 是一个用于从 OpenAPI（前身为 Swagger）定义中生成美观API文档的开放源码工具。它提供了一个响应式的三面板布局：左侧是导航菜单和搜索栏，中间显示文档，右侧则展示请求和响应示例。Redoc 支持 OpenAPI 3.0 和 Swagger 2.0 规范，并且可以通过一些扩展定制你的文档样式。

2. 项目快速启动

安装 Redoc CLI

首先确保你的系统安装了 Node.js，然后通过以下命令全局安装 Redoc 的命令行工具：

npm install -g @redocly/cli

生成静态 HTML 文档

如果你有一个 OpenAPI 文件（例如 openapi.yaml），可以使用以下命令快速生成文档：

npx @redocly/cli build-docs openapi.yaml

这将在当前目录下创建一个名为 redoc-static.html 的文件，可以在浏览器中打开查看。

在网页上集成 Redoc

在HTML页面中引入 Redoc 的库文件并设置 spec-url 属性指向你的 OpenAPI 定义：

<!DOCTYPE html>
<html lang="en">
<head>
    <title>我的API文档</title>
</head>
<body>
    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

将 spec-url 替换为你自己的 OpenAPI JSON 或 YAML 地址。

3. 应用案例和最佳实践

Redoc 被广泛应用于各种组织，包括但不限于 Rebilly, Docker Engine, Zuora, Discourse 等。最佳实践包括：

使用 x-logo 扩展自定义你的品牌标志。
利用 x-tagGroups 建立高级分组以优化侧边栏导航。
提供交互式 "Try it" 控制台以方便测试API。
根据 OpenAPI 定义自动生成代码样本。

4. 典型生态项目

Redoc CLI：用于构建和打包文档的命令行工具，提供额外的 Linting 和 Bundling 功能。
Redocly：Redoc 的商业版本，提供托管的 API 参考文档和更多高级功能。

要了解更多配置和用法，可访问 Redoc 官方文档：https://redocly.github.io/redoc/#configuration。

记得时刻更新 Redoc 版本，以获得最新的特性和改进。祝您使用愉快！

redoc📘 OpenAPI/Swagger-generated API Reference Documentation项目地址:https://gitcode.com/gh_mirrors/re/redoc

顾涓轶

关注

10
点赞
踩
4

收藏

觉得还不错? 一键收藏
打赏
0
评论
Redoc 开源项目教程

Redoc 开源项目教程 redoc???? OpenAPI/Swagger-generated API Reference Documentation项目地址:https://gitcode.com/gh_mirrors/re/redoc 1. 项目介绍Redoc 是一个用于从 OpenAPI（前身为 Swagger）定义中生成美观API文档的开放源码工具。它提供了一个响应式的三面板布局：左侧是...
复制链接

扫一扫