Repository navigation
OpenApiPaths and Operations #472
Description
Hi all
I have a question regarding OpenApiPaths and their operations:
Let's assume I have the following two endpoints:
/api/mp/v1.0/order/{ordernumber}
/api/mp/v1.0/order/{id}
Is this valid from an OpenApi spec point of view?
According to online.swagger.io and OpenApiDiagnostic this is no issue.
Whey are they not combined? Or why is this not a validation issue?
With the following example from an API point of view I don't know what has been called:
/api/mp/v1.0/order/10
code to generate OpenApi spec:
/// <summary>
/// Gets the resource with the specified id.
/// </summary>
/// <param name="id">The resource id.</param>
/// <response code="200">The resource with the specified id.</response>
/// <response code="404">A resource with the specified id could not be found.</response>
[HttpGet("{id}")]
[Authorize(PolicyNames.OrderManagement.CanRead)]
[ProducesResponseType(typeof(OrderReadDTO), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(BaseErrorResult), StatusCodes.Status404NotFound)]
public async Task<IActionResult> GetById(int id)
{
var result = await _OrderService.GetSingleAsync(id);
return new ObjectResult(result);
}
/// <summary>
/// Gets the resource with the specified order number.
/// </summary>
/// <param name="orderno">The resource order number.</param>
/// <response code="200">The resource with the specified order no.</response>
/// <response code="404">A resource with the specified order no could not be found.</response>
[HttpGet("{orderno}")]
[Authorize(PolicyNames.OrderManagement.CanRead)]
[ProducesResponseType(typeof(OrderReadDTO), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(BaseErrorResult), StatusCodes.Status404NotFound)]
public async Task<IActionResult> GetByOrderNo(int orderno)
{
var result = await _OrderService.GetSingleAsync(orderno);
return new ObjectResult(result);
}
Activity
darrelmiller commentedon Apr 26, 2020
The current version of the OpenAPI specification says this scenario is invalid. http://spec.openapis.org/oas/v3.0.3#path-templating-matching
This has been the case since the specification was created. This is one of the many challenges of trying to infer an OpenAPI specification from annotated code. The general consensus in the space is that explicitly creating the OpenAPI document as a design artifact up front is the best way to design APIs using OpenAPI.
There is a proposal on the table to introduce an
priorityproperty that would allow tooling to choose one operation over the other if there is ambiguity. I don't believe this would help the specific case you have shown.fabich commentedon Apr 27, 2020
thanks for your answer Darrel (@darrelmiller)
so shouldn't there be an error when loading a file like this in OpenApiDiagnostic?
I have no issue with this being invalid but the tooling is not reflecting this properly imho.