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

Question

我将 Swashbuckle 与 Redoc 结合使用记录我的 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 , 但找不到生成此类部分的方法。

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

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

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