Enhancement Request: Consistent URI Generation for Swagger API Documentation

Enhancement Request: Consistent URI Generation for Swagger API Documentation

Current Behavior:

Currently, Swagger generates API documentation endpoint paths based on the combination of method names and the "Using" keyword followed by the HTTP method type used in the code. This results in any alteration to method names directly affecting the API documentation URLs.

Desired Enhancement:

I propose an enhancement to the Swagger API documentation generation process. Instead of relying solely on method names, I suggest adopting a more adaptable approach that incorporates both the existing endpoint URI and the HTTP method type associated with each API endpoint.

Example:

For instance, consider the following endpoint definition:

• Method Name: getUserData
• HTTP Method: GET
• Generated Endpoint: GET /getUserData

If the method name is modified to fetchUserData, the current behavior would lead to a change in the documentation URI:

• Before: GET /getUserData
• After: GET /fetchUserData

However, with the proposed enhancement, the documentation URI would remain consistent by considering the HTTP method type along with the endpoint URI:

• Before: GET /getUserData
• After: GET /users (even after method name change)

Advantages:

1. Improved Stability: Method name changes won't impact documentation URIs.
2. Endpoint Consistency: Documentation URIs will consistently match the actual API endpoint URI.
3. Enhanced Readability: Documentation URLs will be more intuitive and easier to manage.

Implementation:

To implement this enhancement, the Swagger generation process could be updated to utilize the existing endpoint URI and the HTTP method type combined to form the documentation URIs.

I believe this enhancement would significantly enhance the usability and maintainability of Swagger-generated API documentation.

Thank you for considering this proposal. Please feel free to request further details or share your thoughts on this approach.

The issue does not identify specific files, tests, or entry points in swagger-ui. Start by locating the Swagger/OpenAPI documentation generation flow and compare its current method-name-derived paths with the endpoint URIs; done means defining and validating consistent generated documentation paths after method renames.