(Bug) Error during diff where spec file contains 2 endpoints with similar but distinct paths about oasdiff HOT 8 CLOSED

I think it is anyway a bad idea to use such endpoints because a lot of middlewares and libraries doesn't support such specifications correctly.
Aspnetcore could try to work with such specifications, but a lot of tools don't even try.

In such case it could be solved. But there are cases when it could not.
E.g. you have 2 endpoints with type: string and different pattern with two different regular expressions. There is no simple algorithm to check properly that these regular expressions don't have intersections or one is a subset of another.

End even in your case it is not so easy to answer what api is /pet/d79d5c7e-e02b-81ed-b5ea-0242ac120002
Is it uuid? But "d79d5c7e-e02b-81ed-b5ea-0242ac120002" is not a correct v1-v5 UUID even if it looks like it. And more, it will be valid UUID if UUID v8 would be released.

It could be both UUID or string and it depends on what types of UUIDs your backend supports.

from oasdiff.

While its a slightly contrived example, it is valid swagger/openapi and displays correctly in swagger-ui and without error in the online swagger.io editor, and they are unique endpoints and not duplicates:

from oasdiff.

Hi @WillGunn and thank you for reporting this.

The OpenAPI specification that you included contains paths that differ only by a path parameter name.
REST considers these paths as equivalent and therefore you effectively have three different definitions for the same API.

For example, consider a developer who relies on this spec to develop a client that needs to get a pet by ID.
Which implementation should they use, /pet/{petId}, /pet/{petId2} or /pet/{petId3}?

Or, consider a server that needs to validate a call to "GET /pet/12345" - which of the three definitions should it use?

Please let me know if you have other thoughts about this.

from oasdiff.

@reuvenharrison So while semantically they are the same route from an HTTP network layer perspective, from an OpenApi/Swagger (application layer) perspective they are different endpoints and backends such as Aspnetcore (which is what we are using) handles them as different endpoints correctly.

Sorry that the example is what you’re getting hung up on. Our actual situation is different and makes more sense to a developer, the file was just made to demonstrate the bug when comparing endpoints that the OpenApi spec says are different. If you want a more realistic scenario that makes sense to a consumer developer, I’ll try to map our real life example onto the pet store. Let me know if that is necessary for you.

Edit: more realistic example added in the below comment

from oasdiff.

I slimmed it down more and this is more in-line with the actual scenario our endpoints are producing.

{
  "openapi": "3.0.3",
  "info": {
    "title": "Swagger Petstore - OpenAPI 3.0",
    "description": "description",
    "version": "1.0.12"
  },
  "servers": [
    {
      "url": "https://petstore3.swagger.io/api/v3"
    }
  ],
  "tags": [
    {
      "name": "pet",
      "description": "Everything about your Pets"
    }
  ],
  "paths": {
    "/pet/{petId}": {
      "delete": {
        "tags": [
          "pet"
        ],
        "summary": "Delete pet by ID",
        "description": "Deletes a single pet by ID",
        "operationId": "deletePetById",
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "description": "ID of pet to delete",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "successful operation"
          }
        }
      }
    },
    "/pet/{animalType}": {
      "delete": {
        "tags": [
          "pet"
        ],
        "summary": "Delete pet(s) by type",
        "description": "Deletes one or more pets by animal type",
        "operationId": "deletePetByAnimalType",
        "parameters": [
          {
            "name": "animalType",
            "in": "path",
            "description": "Animal type of pet(s) to delete",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "Cat",
                "Dog",
                "Parrot",
                "Snake",
                "Bug",
                "Rodent",
                "Misc"
              ]
            }
          }
        ],
        "responses": {
          "204": {
            "description": "successful operation"
          }
        }
      }
    }
  }
}

from oasdiff.

OK, I understand this scenario although I think it might be better to differentiate these two paths, for example:
DELETE /pet/{petId}
DELETE /pet?animalType={type}

You can see a similar discussion here: https://www.mscharhag.com/api-design/rest-deleting-resources

Before considering a code change, would you be able to check this with your team and let us know what they think?

from oasdiff.

Unfortunately the endpoint in question has already been released and is in use in production via external consumers.

from oasdiff.

OK, I'll see what can be done.

from oasdiff.