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

Что можно добавить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.
        ",
});