您如何在NSwag生成的API文档网站上添加“常规信息”部分？

Question

我们当前的方法使用手动维护并格式化的YML文档。首先，我想在生成的文档中包括冗长的介绍/说明部分。敏捷的文档建议我可以添加与markdown兼容的多行描述，但这并不是我真正想要在Startup.cs文件中执行的操作。如何添加这种扩展的介绍？

使用Redoc生成的docs.discourse.org上显示了我要执行的操作的示例。

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"));
});