Aicrosoft.Extensions.Swagger 8.0.0-beta.260127.1

Aicrosoft.Extensions.Swagger

Aicrosoft.Extensions.Swagger is a high-level wrapper and extension for Swashbuckle.AspNetCore, designed to provide consistent, powerful, and easy-to-configure API documentation support for microservices or modular web applications under the Aicrosoft framework.

Design Goals

1. Automated Modular Grouping: Implements automatic grouping based on the assembly (module) where controllers reside using IApiDescriptionGroupCollectionProvider, solving the issue of API clutter in large projects.
2. Unified Security & Authorization: Built-in support for JWT (Bearer) and OAuth2, providing AuthorizeCheckOperationFilter to automatically show or hide lock icons on the UI based on code attributes ([Authorize] / [AllowAnonymous]).
3. Multi-version Compatibility: Seamlessly integrates with Asp.Versioning, supporting the generation of different document definitions based on version numbers.
4. Standardized Output: Provides out-of-the-box features like URL lowercasing, obsolete interface tagging, and automatic merging of XML comments from multiple projects.
5. Configuration-Driven: Deeply integrated with AppSettings, allowing dynamic enabling/disabling of Swagger and detailed authorization configuration via configuration files.

Key Features

• Module Grouping: Automatically identifies GroupName and maps it to a Swagger Endpoint.
• JWT Lock Icons: Automatically recognizes authentication attributes, eliminating the need for complex manual OpenApiSecurityRequirement configuration.
• Path Transformation: PathLowercaseDocumentFilter ensures RESTful paths comply with lowercase conventions.
• Cross-module XML Comments: Automatically loads XML comment files related to plugin assemblies.
• Anonymous Access Protection: Automatically configures middleware to allow access to /swagger even when global authentication is enabled.

Usage

1. Installation

Reference the following package in your web project (typically the Host or Api project):

• Aicrosoft.Extensions.Swagger

2. Define Swagger Configuration Class

Inherit from SwaggerGroupConfigureOptions to define your API description mapping logic:

public class MySwaggerOptions(IServiceProvider provider) : SwaggerGroupConfigureOptions(provider)
{
    protected override OpenApiInfo CreateModuleOpenApiInfo(Assembly moduleAssembly, IEnumerable<ApiVersion>? apiVersions = null)
    {
        return new OpenApiInfo
        {
            Title = $"My API - {moduleAssembly.GetName().Name}",
            Version = apiVersions?.FirstOrDefault()?.ToString() ?? "v1",
            Description = "API documentation for my service modules."
        };
    }
}

3. Register Services in WebApplicationBuilder

var builder = WebApplication.CreateBuilder(args);

// Register Swagger service and bind the configuration class
builder.AddSwaggerService<MySwaggerOptions>();

var app = builder.Build();

// Enable Swagger middleware
app.UseSwaggerService();

app.Run();

4. Configuration (appsettings.json)

{
  "SwaggerUI": {
    "Enable": true,
    "ClientId": "your-client-id",
    "Scopes": {
      "api.read": "Read access to the API",
      "api.write": "Write access to the API"
    }
  },
  "Auth": {
    "Enable": true
  }
}

Notes

• XML Comments: To see method comments on the UI, ensure <GenerateDocumentationFile>true</GenerateDocumentationFile> is enabled in your WebAPI projects' .csproj files.
• Path Conflicts: PathLowercaseDocumentFilter is enabled by default. If your code has explicit case dependencies in paths, please adjust accordingly.
• Grouping Rules: Grouping is based on ApiExplorerSettings(GroupName = "...") by default. If GroupName is not specified, it may not be correctly mounted to an endpoint.