使用 Swashbuckle 将文本部分添加到 Swagger

Question

我使用 Swashbuckle 和Redoc来记录我的 ASP.NET Core 2.2 API。实时 ReDoc 演示在顶部有一组部分（例如“简介”），其中包含一些自定义 html。我想在 API 中生成类似的部分，但不知道如何执行。

基本上我有：

services.AddSwaggerGen(c => {
    c.SwaggerDoc(...);
    c.IncludeXmlComments(...);
    c.AddSecurityDefinition("OAuth2", ...);
});

然后：

app.UseReDoc(c => {
    c.SpecUrl = "/swagger/v1/swagger.json";
    c.RoutePrefix = "";
});

我已经浏览了 intellisense 选项以及 Swashbuckle readme和wiki，但找不到生成此类部分的方法。

将 HTML 部分添加到基于 Swashbuckle.AspNetCore.ReDoc 的文档的开头的方法是什么？

Answer 1

您可以在传递到 的Description中使用 markdown 。您可以包含标题，这些标题最终将作为 ReDoc 中的侧栏导航项。例如：InfoSwaggerDoc(...)

c.SwaggerDoc(Version, new Info
    {
        Title = "My API",
        Description = @"This is our API.

            ## Introduction

            We can use markdown (with [links](https://example.org)) to explain more about the API.

            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

            - Bullet item
            - And another bullet item

            Some more lorem ipsum.

            ## Logging

            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

            Here's a sample block:

            ```bash
            curl https://example.org/api/v1/some-method \
            -H 'X-Header: value' \
            -v
            ```

            Lorem ipsum **doler sit met something more** test text.
        ",
});

我建议将该 markdown 放入嵌入式资源文件（例如api-intro.md）中并在运行时读取它。