[Swagger] Append information about api possible versions

[westfin]

Hi guys, this question partially related to #998

My X-Api-Version header parameter appeared in openapi document (snippet below). Does it possible to list possible version values for api? Currently we have only one active 1.0 version. But our clients want to see such info in document.

parameters:
  - name: X-API-Version
    in: header
    description: The requested API version
    schema:
       type: string

Maybe if it is valid schema something like:

parameters:
  - name: X-API-Version
    in: header
    description: The requested API version
    schema:
       type: string
       enum: 
         - "1.0"
         - "2.0"
         - null

[commonsensesoftware]

Yes, but it comes with some caveats. API versions are collated by logical API, not by endpoints. This is also the same way they are listed in OpenAPI. There are typically many endpoints per API. It is definitely possible to list all possible API versions, but know that it is possible that showing that in the UI might present an API version that is not actually implemented. This is most likely to happen if you select an API version for an endpoint that was removed in a later version. Another problem can occur if the API accepts a body that is different across API versions.

The UI will show all of the available API versions as the group name. An OpenAPI document must have unique URLs, so there is typically one document per API version. The only exception would be if you version by URL segment, which I don't recommend (as it's not RESTful).

This is the place in the example that shows how to set the default value for the API version:

aspnet-api-versioning/examples/AspNetCore/WebApi/OpenApiExample/SwaggerDefaultValues.cs

Line 59 in f29831e

parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson( json );

If you add the following small change, then it will become an enumeration:

var metadata = apiDescription.ActionDescriptor.GetApiVersionMetadata();
var model = metadata .Map(ApiVersionMapping.Explicit | ApiVersionMapping.Implicit);
var @enum = from version in model.ImplementedApiVersions
            select OpenApiAnyFactory.CreateFromJson(JsonSerializer.Serialize(version.ToString(), modelMetadata.ModelType));

parameter.Schema.Enum = @enum.ToList();

This will produce the dropdown with all of the implemented API versions, but not necessarily available for that specific endpoint.

A better approach might be to list all of the API versions as extension metadata to the OpenAPI document itself. This could be a list of all versions, supported versions, deprecated versions, or just links to other OpenAPI documents. This approach would provide the metadata that clients may be looking for while keeping the current document truthful.