Support returning OpenAPI document in YAML from MapOpenApi by captainsafia · Pull Request #58616 · dotnet/aspnetcore (original) (raw)

Addresses #58516.

This PR adds support for returning the OpenAPI document at runtime in the YAML format. It does this by checking the extension on the route pattern that is provided for resolving the OpenAPI document. If a user calls:

app.MapOpenApi("/openapi/{documentName}.yaml");

Then visiting the /openapi/v1.yaml route in their application will return the document in YAML format. The implementation treats routes ending in either yaml or yml as YAML-generating by default. All other routes will produce an OpenAPI document serialized to JSON.

As an alternative approach, we could follow the pattern proposed in this issue and introduce an additional OpenApiFormat argument to the MapOpenApi method. However, because the implementation assumes that the extension appears in the route pattern by default we run the risk of users inadvertently calling:

app.MapOpenApi(format: OpenApiFormat.Yaml);

Which would use the default route pattern for the document that uses a JSON file extension with the incorrect file format. I figured it was more straightforward if we define the format based on the route pattern and avoid adding another option. There is a risk that more formats get added in the future and the complexity of our checks increases but that isn't a likely eventuality at the moment.