search

microsoft / OpenAPI.NET

The OpenAPI.NET SDK contains a useful object model for OpenAPI documents in .NET along with common serializers to extract raw OpenAPI JSON and YAML documents from the model.
MIT License
1.42k stars 240 forks source link

Version 1.6.5 to 1.6.13 contains breaking change #1572

Open JohannesBauer97 opened 9 months ago

JohannesBauer97 commented 9 months ago

Describe the bug We're using this package to validate OpenAPI specification files by reading the files OpenApiStringReader.Read and checking if there are diagnostic errors. image

After updating from 1.6.5 to 1.6.13, a spec which was valid before, became invalid because of non-unique paths (see below the screenshot).

Diagnostic Error: RuleName: "PathMustBeUnique" Pointer: "#/paths//api/v1/{birdId}/children/{childNo}" Message: "The path signature '/api/v1/{}/children/{}' MUST be unique."

OpenApi File To Reproduce Just giving a screenshot here, if the full file is required I need to anonymize it first. Maybe for the discussion the screenshot is enough image

Expected behavior No breaking changes between patch versions.

What does the openapi spec say? Is this definition of non unique paths a error?

VisualBean commented 9 months ago

Technically, the new behavior is correct. From https://spec.openapis.org/oas/v3.0.3#paths-object

A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object’s url field in order to construct the full URL. Path templating is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it’s up to the tooling to decide which one to use.

4.7.8.2 Path Templating Matching § Assuming the following paths, the concrete definition, /pets/mine, will be matched first if used:

  /pets/{petId}
  /pets/mine

The following paths are considered identical and invalid:

  /pets/{petId}
  /pets/{name}

The following may lead to ambiguous resolution:

  /{entity}/me
  /books/{id}

Due to templating behavior, those paths are indeed considered identical.

JohannesBauer97 commented 9 months ago

Thanks for the reference, so it was all the time defined like this, and now it got fixed in the nuget.

rasmus-s commented 9 months ago

@VisualBean the new behavior have one issue as I see it, it not taking the apiOperation into account with different template names. Should below not be allowed?

DELETE /pets/{petId} PUT /pets/{name}