在 Web 开发中，文档对于前端开发者来说是极其重要的。而 Swagger/OpenAPI 规范已经成为了 API 文档的事实标准。但是，Swagger 默认提供的文档界面并不美观。我们需要一个更好的 Swagger 文档阅读器。而 redoc 就是一个优秀的 Swagger 文档阅读器，它是一个基于 React 的 Web 组件，可以渲染出美观且高度可定制的 Swagger 接口文档页面。
在本文中，我将会向你介绍 npm 包 redoc 的使用方法，并提供示例代码。
redoc 简介
redoc 是一个基于 React 和 Redux 的 Web 组件，可以渲染出美观且高度可定制的 Swagger 接口文档页面。它支持自动解释 Swagger 规范定义的各种数据类型和 API 路径，使得文档易于阅读和理解。
与 Swagger-UI 不同，redoc 的主要定位是对文档的美观和定制性。它提供了众多美观的主题以及自定义组件的能力，可以根据项目需求随意修改界面。
redoc 的安装
redoc 是一个 npm 包，可以通过 npm 安装它。
npm install redoc
redoc 的使用
redoc 的使用非常简单。你只需要在你的 React 项目中引入 RedocCompoment 组件并传入要渲染的 Swagger 规范文件即可。
import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { RedocCompoment } from 'redoc';
ReactDOM.render(
<RedocCompoment specUrl="/api/swagger.json" />,
document.getElementById('root')
);redoc 的定制
redoc 提供了非常强大的定制能力。你可以通过配置一些属性来定制你的文档界面。下面是一些常用的配置属性，更详细的配置列表可以在官方文档中找到。
theme 属性
使用 theme 属性可以选择一个适合的主题，用于定制文档的外观。
<RedocCompoment specUrl="/api/swagger.json" theme={{ colors: { primary: { main: '#3f51b5' } } }} />在上面的示例中，我们定制了主题的 primary 颜色为 #3f51b5。
options 属性
使用 option 属性可以修改一些基本配置，例如是否允许展开所有组件。
<RedocCompoment specUrl="/api/swagger.json" options={{ expandResponses: 'all' }} />在上面的示例中，我们允许展开所有的响应组件。
components 属性
使用 components 属性可以重写 redoc 中的某些组件，用自定义组件代替。
import { RequestSamples } from './RequestSamples';
<RedocCompoment
specUrl="/api/swagger.json"
components={{
RequestSamples,
}}
/>在上面的示例中，我们重写了 redoc 中的 RequestSamples 组件，用自定义的 RequestSamples 组件代替。
示例代码
下面是一个完整的使用 redoc 的示例代码。
-- -------------------- ---- -------
------ - -- ----- ---- --------
------ - -- -------- ---- ------------
------ - -------------- - ---- --------
----- --- - -- -- -
------ -
---------------
---------------------------
-------- ------- - -------- - ----- --------- - - --
---------- ---------------- ----- --
------------- -------------- --
--
--
--
----- -------------- - ------- -- -
----- - ------- - - ------
------ -
-----
--------------------- -- -- -
---- --------
----------------------
----------------------------
------
---
------
--
--
-------------------- --- ---------------------------------以上就是 npm 包 redoc 的使用教程。希望这篇文章能够帮助你更好的使用和定制 redoc。当然，你也可以在项目官方文档中找到更详细的配置属性与示例。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5f091e4d403f2923b035c00c