How do you add a "general info" section to an NSwag generated API document website?

Question

Our current method uses a manually maintained and formatted YML document. At the beginning is a lengthy introduction/instruction section that I would like to include in generated documentation. The swagger docs suggest that I can add a markdown compatible, multi-line description but that's not really something I want to do in my Startup.cs file. How can I add this sort of extended introduction?

An example of the what I'm looking to do is shown on docs.discourse.org which is generated using Redoc.

Answer 1

I would suggest placing your API introduction to a static file that is copied to build output, then configure open api document to read it.

The file can contain HTML markup or markdown. I tend to use markdown to get heading links appear in the sidebar in redoc, it is completely up to you.

services.AddOpenApiDocument(document =>
{ 
    document.Description = File.ReadAllText("Docs/Description.html");

    // other properties

    document.AddSecurity("Bearer", Enumerable.Empty<string>(), new OpenApiSecurityScheme
    {
        Type = OpenApiSecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = OpenApiSecurityApiKeyLocation.Header,
        Description = File.ReadAllText("Docs/Authentication.html")
    });
    document.OperationProcessors.Add(new AspNetCoreOperationSecurityScopeProcessor("Bearer"));
});