How do you add a "general info" section to an NSwag generated API document website? - asp.net-core

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