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 https://github.com/dotnet/aspire/issues/2980

[sayedihashimi]

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