MvcBuilderExtensions Class
HAKOM.Documentation.Http.Net.Api.Extensions
Section titled “HAKOM.Documentation.Http.Net.Api.Extensions”Contains methods for adding documentation functionality to an MVC framework based web service.
public static class MvcBuilderExtensionsInheritance System.Object 🡒 MvcBuilderExtensions
Fields
Section titled “Fields”MvcBuilderExtensions.DEFAULT_SERVICE_TITLE Field
Section titled “MvcBuilderExtensions.DEFAULT_SERVICE_TITLE Field”The title of the service that will be used in any generated OpenAPI document if no other title is available.
public const string DEFAULT_SERVICE_TITLE = "Untitled Service";Field Value
Section titled “Field Value”Methods
Section titled “Methods”MvcBuilderExtensions.AddDocumentation(this IMvcBuilder, string, string, string, string, string, string, Action<SwaggerGenOptions>) Method
Section titled “MvcBuilderExtensions.AddDocumentation(this IMvcBuilder, string, string, string, string, string, string, Action<SwaggerGenOptions>) Method”Adds automatically generated OpenAPI documentation to an HTTP API.
public static Microsoft.Extensions.DependencyInjection.IMvcBuilder AddDocumentation(this Microsoft.Extensions.DependencyInjection.IMvcBuilder builder, string? title=null, string? description=null, string? fileNamePrefix=null, string? xmlFileNamePattern=null, string versionSeparator="-", string basePath="documentation", System.Action<Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenOptions>? swaggerGenSetup=null);Parameters
Section titled “Parameters”builder Microsoft.Extensions.DependencyInjection.IMvcBuilder
The Microsoft.Extensions.DependencyInjection.IMvcBuilder to add the documentation to.
title System.String
A title of the API to be used for the service in the OpenAPI document. If null but a singleton service for IServiceInformation has previously been registered, that implementations Title property will be used. If not available, the title will simply fallback to DEFAULT_SERVICE_TITLE.
description System.String
A description of the API to be used in the OpenAPI document. If null, but a singleton service for IServiceInformation has previously been registered, that implementations Description property will be used. If not available, the description will simply fallback to an empty string.
fileNamePrefix System.String
The file name for the OpenAPI document. This will be suffixed by the APIs version. If null this will be the lower case of the assembly name followed by a hyphen or if the assemblies name is null, the constant “openapi-”.
xmlFileNamePattern System.String
If XML comments should be used in the generation of the document and the generated XML documentation file is not named after the assembly (default behavior in Visual Studio), specify the name of the files here. Relative pathes are based in the working directory of the application.
versionSeparator System.String
The string to use in the final file name for the OpenAPI document between fileNamePrefix and the documents version.
basePath System.String
The base path under which the documentation should be published.
swaggerGenSetup System.Action<Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenOptions>
An action that can be used to customize the documentation. See the official Swashbuckle documentation for details.
Returns
Section titled “Returns”Microsoft.Extensions.DependencyInjection.IMvcBuilder
The builder for chaining any additional setup.
Remarks
Section titled “Remarks”When used, a new endpoint will be added to the API (basePath/) which will redirect to the latest version generated for the API (one service may support multiple versions).
If available, XML comments will be used to generate descriptions in the OpenAPI document.
This uses Swashbuckle to generate the documentation based on the MVC controllers registered with the application. For more information on how to modify the generated document, please consult the official Swashbuckle documentation.
MvcBuilderExtensions.AddTagDescription(this IMvcBuilder, string, string, int) Method
Section titled “MvcBuilderExtensions.AddTagDescription(this IMvcBuilder, string, string, int) Method”Adds a description to tags used to group endpoints in OpenAPI documents.
public static Microsoft.Extensions.DependencyInjection.IMvcBuilder AddTagDescription(this Microsoft.Extensions.DependencyInjection.IMvcBuilder mvcBuilder, string tag, string description, int order=0);Parameters
Section titled “Parameters”mvcBuilder Microsoft.Extensions.DependencyInjection.IMvcBuilder
The Microsoft.Extensions.DependencyInjection.IMvcBuilder used to configure the application for which a specific auto-generated documentation tag should be extended with a description.
tag System.String
The tag that this description applies to. When multiple AddTagDescription(this IMvcBuilder, string, string, int) calls are performed with the same tag, the last description added during configuration will be used.
description System.String
A short text describing what endpoints grouped by this tag have in common.
order System.Int32
When specified, determines the relative order by which the tag is to be sorted. Tags are sorted by order first, then alphabetically by tag.
Returns
Section titled “Returns”Microsoft.Extensions.DependencyInjection.IMvcBuilder
The mvcBuilder for chaining of additional setup.
Remarks
Section titled “Remarks”When adding automatically generated OpenAPI documentation via AddDocumentation(this IMvcBuilder, string, string, string, string, string, string, Action<SwaggerGenOptions>) to an MVC framework based HTTP API, all endpoints are automatically grouped using tags generated based on their namespace. In addition, individual controllers and actions can have tags assigned by using the Microsoft.AspNetCore.Http.TagsAttribute.
In order to add a short description to a tag that explains in a little more detail what the endpoints that are grouped by that particular tag have in common, call this method on the mvcBuilder.