ReDoc
ReDoc 是一个使用 OpenAPI 规范生成文档的工具，支持多种语言和框架。在 .NET 中，使用 Swagger UI 或 Swashbuckle 可以方便地生成文档，但是 ReDoc 的渲染效果更好，而且支持多种自定义选项。在本文中，我们将介绍如何在 .NET 中使用 ReDoc 生成文档，并提供详细的使用示例。
# 安装
在使用 ReDoc 之前，需要先安装它。可以使用 npm 进行安装，也可以直接下载预编译的文件。在 .NET 中，我们通常会选择下载预编译的文件，因为这样可以方便地集成到项目中。可以从 ReDoc 的官方网站 (opens new window) 下载最新版本的文件。
# 集成到 .NET 项目中
有多种方法可以将 ReDoc 集成到 .NET 项目中。下面介绍其中两种常见的方法。
# 方法一：使用 HTML 文件引用
首先，将下载的 ReDoc 文件解压到项目的静态文件目录中，例如 wwwroot 目录。然后，创建一个 HTML 文件，用于加载 ReDoc 并指定要渲染的 OpenAPI 规范文件。以下是一个示例文件：
<!DOCTYPE html>
<html>
<head>
<title>ReDoc Demo</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="/redoc/redoc.min.css" />
</head>
<body>
<redoc spec-url="/swagger/v1/swagger.json"></redoc>
<script src="/redoc/redoc.min.js"></script>
</body>
</html>
在这个文件中，我们首先引用了 ReDoc 的 CSS 文件，然后在 <body> 中添加了一个 <redoc> 元素，用于指定要渲染的 OpenAPI 规范文件的 URL。在这个示例中，我们使用了 ASP.NET Core 中自带的 Swagger UI 生成的规范文件。最后，我们引用了 ReDoc 的 JavaScript 文件。
# 方法二：使用 ASP.NET Core 中间件
另一种常见的方法是使用 ASP.NET Core 中间件来集成 ReDoc。这种方法比较灵活，可以更方便地进行配置。下面是一个示例：
app.UseReDoc(options =>
{
options.SpecUrl = "/swagger/v1/swagger.json";
options.RoutePrefix = "redoc";
options.DocumentTitle = "ReDoc Demo";
});
在这个示例中，我们使用了一个名为 UseReDoc 的中间件，用于指定要渲染的 OpenAPI 规范文件的 URL，并设置了一些其他的选项，例如路由前缀和文档标题。
# 配置选项
ReDoc 提供了许多自定义选项，可以用来调整渲染的效果
下面是一些常见的选项：
specUrl：要渲染的 OpenAPI 规范文件的 URL。theme：主题选项，可以选择默认的明亮或暗黑主题，或者自定义主题。scrollYOffset：滚动偏移量，用于控制页面滚动时的偏移量。hideDownloadButton：是否隐藏下载按钮。hideLoading：是否隐藏加载动画。untrustedSpec：是否允许渲染不受信任的规范文件。
可以在 ReDoc 的官方文档中查看完整的选项列表和说明。
# 使用示例
在使用 ReDoc 生成文档时，我们需要先准备一个 OpenAPI 规范文件。在 .NET 中，可以使用 Swagger UI 或 Swashbuckle 来生成规范文件。以下是一个使用 Swashbuckle 生成规范文件的示例：
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "MyApi.xml"));
});
在这个示例中，我们使用了 AddSwaggerGen 方法来配置 Swashbuckle，并生成了一个名为 v1 的规范文件。同时，我们还指定了一个 XML 文档文件，用于生成 API 文档注释。
接下来，我们需要将生成的规范文件传递给 ReDoc，进行渲染。我们可以使用之前介绍的两种方法之一来集成 ReDoc。以下是一个使用 HTML 文件引用的示例：
<!DOCTYPE html>
<html>
<head>
<title>ReDoc Demo</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="/redoc/redoc.min.css" />
</head>
<body>
<redoc spec-url="/swagger/v1/swagger.json"></redoc>
<script src="/redoc/redoc.min.js"></script>
</body>
</html>
在这个示例中，我们指定了要渲染的规范文件的 URL 为 /swagger/v1/swagger.json，这与之前配置 Swashbuckle 时生成的规范文件相对应。在浏览器中打开这个 HTML 文件，就可以看到生成的 API 文档了。
# 结论
ReDoc 是一个强大的文档生成工具，可以方便地生成漂亮、易读的 API 文档。在 .NET 中，我们可以使用 Swagger UI 或 Swashbuckle 来生成 OpenAPI 规范文件，然后使用 ReDoc 来渲染这些规范文件。通过选择适合自己的集成方法和配置选项，我们可以轻松地生成高质量的文档，帮助我们更好地理解和使用 API。