LSL.Swashbuckle.AspNetCore 1.0.4

LSL.Swashbuckle.AspNetCore

This package provides extensions to Swashbuckle.AspNetCore and Asp.Versioning.Mvc.ApiExplorer to provide a quicker route to implement versioning in an API.

Quick Start

The following code shows the setting up of an API to use all of the provided extensions:

using LSL.Swahbuckle.AspNetCore
...
// Within ConfigureServices

// Adds the information found in "Program"'s assembly's AssemblyInformationalVersionAttribute to generated OpenApi documents
// this is then found under the "x-code-version" property under the standard "info" property in the OpenApi document
// Properties of "x-code-version":
//  "version": the assembly version
// "commitHash": the githash if found in the AssemblyInformationalVersionAttribute,
// "commitUrl": only setup if a call is made to add the commit hash url (the following sets up a URL for Azure devops)
//      This is optional but when applied then any call to AddCodeVersionToApiDescription
//      will add a link to the version number to the commit
//      Other methods to setup the url are included for GitHub And BitBucket:
//          AddUrlForGitHubCommit
//          AddUrlForBitBucketCommit
services.AddCodeVersionForAssemblyOf<Program>(c => c.AddUrlForDevopsGitCommit("MyOrg", "MyProject", "MyRepo"))
    // Ensures all versions of the API are available in swagger UI
    .AddSwaggerGenWithVersioning(c =>
    {
        // Shows the code version in the Swagger UI description
        c.AddCodeVersionToApiDescription()
            // Picks up the xml comments for the assembly of the provided class (Program in this case)
            .AddXmlCommentsForAssemblyOf<Program>()
            // Adds a schema filter to automatically convert enums to strings
            .AddStringEnumFilter()
            // Populates the OpenApi documents with a list of server Urls (just one picked up here from the API's configuration)
            .WithServerUrls(new[] { builder.Configuration.GetValue<string>("SwaggerServerUrl")! })
            // Sets up the Swagger UI title (shown in the UI - not the html title) from the assembly name
            // of the provided class
            .WithTitleFromAssemblyOf<Program>();
    },
    // Allows for further configuration of the ApiVersioningOptions
    apiVersioningConfigurator: o => { }
    // Allows for further configuration of the ApiExplorerOptions
    // Default Version number format is "VVV" and a groupNameFormat of "'v'VVV"
    apiExplorerConfigurator: o => o.WithVersionNumberFormat("VV"));

...

var app = builder.Build();


// Enables swagger UI with versioning
app.UseSwaggerUIWithVersioning(c => 
{
    // Sets the html document title to "{assemblyName} - Swagger UI"
    c.AddDocumentTitleFromAssemblyOf<Program>();
});