如何将 "general info" 部分添加到 NSwag 生成的 API 文档网站？

Question

我们当前的方法使用手动维护和格式化的 YML 文档。开头是一个冗长的 introduction/instruction 部分，我想将其包含在生成的文档中。 swagger 文档建议我可以添加一个 markdown 兼容的多行描述，但这并不是我真正想在我的 Startup.cs 文件中做的事情。如何添加这种扩展介绍？

docs.discourse.org 中显示了我想要执行的操作的示例，它是使用 Redoc 生成的。

Answer 1

我建议将您的 API 介绍放在复制到构建输出的静态文件中，然后配置打开 api 文档以阅读它。

文件可以包含 HTML 标记或降价。我倾向于使用 markdown 来让标题链接出现在 redoc 的侧边栏中，这完全取决于你。

services.AddOpenApiDocument(document =>
{ 
    document.Description = File.ReadAllText("Docs/Description.html");

    // other properties

    document.AddSecurity("Bearer", Enumerable.Empty<string>(), new OpenApiSecurityScheme
    {
        Type = OpenApiSecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = OpenApiSecurityApiKeyLocation.Header,
        Description = File.ReadAllText("Docs/Authentication.html")
    });
    document.OperationProcessors.Add(new AspNetCoreOperationSecurityScopeProcessor("Bearer"));
});

如何将 "general info" 部分添加到 NSwag 生成的 API 文档网站？

How do you add a "general info" section to an NSwag generated API document website?

asp.net-core

openapi

nswag