Support Template Substitutions for URL Segment Versioning

[commonsensesoftware]

Background

The API Explorer correctly discovers API versions described in URL segments as a parameter to an API; however, service authors who use this style of API versioning typically do not want to the parameter to be exposed in tools like Swagger.

The API Explorer normally produces results like:

template: api/v{version}/resource
parameters: [{ name: 'version', defaultValue: '1.0' }]

Service authors that version by URL segment instead prefer:

template: api/v1/resource
parameters: []

Proposal

To support this scenario, the API Explorer should allow a configuration option to trigger this behavior when generating API descriptions. This would include the following features:

• Trigger opt-in behavior using a new API explorer option (ex: SubstituteApiVersionInUrl)
• Replace the route parameter in route templates (ex: {version}) with the associated API version
• Remove the substituted API version parameter from the associated API description
• Add an option to support the formatting the API version (ex: SubstitutionFormat) based on the supported formatting options