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

Question

我正在使用带有 Redoc 的 Swashbuckle 来记录我的 ASP.NET Core 2.2 API。 The live ReDoc demo 在顶部有一组部分（例如“简介”），带有一些自定义 html。我想在我的 API 中生成类似的部分，但不知道该怎么做。

基本上我有：

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

后来：

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

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

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

Answer 1

您可以在传递给SwaggerDoc(...) 的Info 的Description 中使用markdown。您可以在 ReDoc 中包含最终作为侧边栏导航项的标题。例如：

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

我建议将该降价放在 embedded resource file (e.g. api-intro.md) and reading it runtime 中。