Добавьте текстовые разделы в Swagger, используя Swashbuckle

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, а также readme и wiki Swashbuckle, но не нашел способа создать такие разделы.

Как добавить разделы HTML в начало документации на основе Swashbuckle.AspNetCore.ReDoc?

Answer 1

Вы можете использовать уценку в Description из Info перешел к SwaggerDoc(...), Вы можете включить заголовки, которые в 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.
        ",
});