Add textual sections to Swagger using Swashbuckle

Question

I'm using Swashbuckle with Redoc to document my ASP.NET Core 2.2 API. The live ReDoc demo has a set of sections at the top (e.g. "Introduction") with some custom html. I want to generate similar sections in my API but can't see how to do so.

Basically I have:

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

And later:

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

I've ran through the intellisense options, as well as the Swashbuckle readme and wiki, but found no way to generate such sections.

What's the way to add HTML sections to the start of Swashbuckle.AspNetCore.ReDoc based documentation?

Jeroen · Answer 1 · 2020-12-03T05:41:01.247

You can use markdown in the Description of Info passed to SwaggerDoc(...). You can include headers which will end up as side-bar navigation items in ReDoc. E.g.:

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

I recommend putting that markdown inside an embedded resource file (e.g. api-intro.md) and reading it runtime.

Is there a way to do this that doesn't involve sticking large chunks of text into Startup.cs? — nathanjw, Dec 02 '20 at 17:37
@nathanjw Yes, and I typically do so, in fact. Added a link to the bottom of my answer with this approach. — Jeroen, Dec 03 '20 at 05:41
You could of course also use any other method to encapsulate and move that string (simplest would be a `SwaggerConstants.cs` file with strings). — Jeroen, Dec 03 '20 at 05:42
that's how we did it in the end. was way simpler than we thought it was going to be with having to mess around with a custom index.html file and css. thanks for posting the link :) — nathanjw, Dec 04 '20 at 15:51

Add textual sections to Swagger using Swashbuckle

1 Answers1

Linked