Feature Proposal: Centralized Swagger UI for OpenAPI Specification Files

[AClerbois]

Feature Proposal

Summary

In the context of the .NET Aspire project, I propose to add a new feature aimed at consolidating all OpenAPI specification files across the project into a unified Swagger UI interface. This would greatly enhance the developer experience by providing a single, centralized location to view and interact with the API documentation generated from OpenAPI specifications.

Problem Statement

Currently, OpenAPI specification files are scattered throughout various parts of our project, making it challenging to locate, view, and test different APIs efficiently. Developers and API consumers have to navigate through multiple Swagger UI instances or look into different directories to find the relevant API documentation. This fragmentation hinders productivity and can lead to inconsistencies in how APIs are understood and used.

Proposed Solution

Implement a mechanism within the .NET Aspire project that automatically scans the project directories for OpenAPI specification files (*.json or *.yaml). Once identified, these files will be aggregated into a single Swagger UI instance. This unified Swagger UI will be automatically updated to reflect changes in the OpenAPI specifications, ensuring that the documentation is always current.

Benefits

• Centralization: Provides a one-stop-shop for all API documentation, making it easier for developers to find and use the APIs they need.
• Improved Developer Experience: Facilitates a smoother development process by reducing the time spent searching for API documentation.
• Consistency: Ensures that all API documentation is presented in a consistent manner, aiding in understanding and integration efforts.
• Automation: Reduces manual effort required to maintain API documentation visibility as the project evolves.

Implementation Considerations

• The scanning mechanism should be configurable to allow for inclusion or exclusion of specific directories or files.
• Consideration should be given to how the unified Swagger UI is hosted within the project (e.g., as part of the build process, within a container, etc.).
• Security implications of aggregating and exposing API documentation in a single location should be assessed and mitigated.

Request for Comments

I invite the community to provide feedback on this proposal. Any insights on potential challenges, additional benefits, or alternative approaches to achieving this goal would be greatly appreciated.

[davidfowl]

Cool idea, related to #2980

[sayedihashimi]

If we do this we should also support it in Visual Studio.

[Foxtrek64]

Just some (half-baked) general thoughts to help spur discussion

• Dedicated Swagger service container

var builder = DistributedApplication.CreateBuilder(args);
var swagger = builder.AddSwaggerHost("swagger");

builder.AddProject<Projects.MyCoolProject>("web")
       .WithReference(swagger);

• A few discovery mechanism ideas

var swagger = builder.AddSwaggerHost("swagger")
    .WithSwaggerFile("**/*.swagger.json"); // With glob to point to swagger files

var someService = builder.AddNonDotNetService("foo")
    .WithSwagger(); // Search output path for swagger file. Possibly accept glob pattern again. Intended scenario is including a swagger file from a docker image or something similar.

var web = builder.AddProject<Projects.MyCoolProject>("web")
    .WithReference(swagger);

// In MyCoolProject.Project.cs
var builder = WebApplication.CreateBuilder(args);
builder.AddSwagger("swagger"); // Wraps standard swagger packages to produce the swagger json file, then provides that back to the swagger host.

My Questions

• What kind of ergonomics do we want here?
• Should supporting DotNet projects (a la AddProject<TProject>(string)) feel different than supporting non-DotNet projects (e.g. a PHP web service)?
  • If so, how? Why?
• How should we handle IDP support, e.g. if Keycloak is used as an auth source for the application overall, how do we secure Swagger with it?
  • This likely falls under the umbrella of IDP integration with Aspire overall and might be a little out of scope.