search

OpenAPITools / openapi-diff

Utility for comparing two OpenAPI specifications.
Apache License 2.0
778 stars 153 forks source link

Servers.Url are not considered when path changes #585

Closed Fresa closed 6 months ago

Fresa commented 7 months ago

Moving a servers.url moniker to a path causes openapi-diff to falsely detect a breaking change.

Example:

openapi: "3.1.0"
servers:
  - url: /v1
paths:
  /foo
    get:
...

Changing to:

openapi: "3.1.0"
servers:
  - url: /
paths:
  /v1/foo
    get:
...

Result:

--                              What's New                              --
--------------------------------------------------------------------------
- GET    /v1/foo

--------------------------------------------------------------------------
--                            What's Deleted                            --
--------------------------------------------------------------------------
- GET    /foo
--------------------------------------------------------------------------
--                                Result                                --
--------------------------------------------------------------------------
                 API changes broke backward compatibility                 
--------------------------------------------------------------------------

Tested with openapitools/openapi-diff:2.1.0-beta.6

joschi commented 6 months ago

@Fresa Could you please elaborate? I think this definitely is a breaking change for any client.

servers.url is usually what a client configures itself. Sometimes there's only one canonical URL, but usually that's what you're using to distinguish different deployments of an HTTP API.

paths.* on the other hand is what the clients would be using against the deployment of the HTTP API at servers.url and changing these will break clients.

Fresa commented 6 months ago

Full API urls are defined by the expanded server.url with the path key property appended.

The two examples I posted defines the same full url, and therefor is no breaking change IMO.

https://spec.openapis.org/oas/v3.1.0#patterned-fields:

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

joschi commented 6 months ago

The two examples I posted defines the same full url, and therefor is no breaking change IMO.

Sure, there might be special cases in which this is not a breaking change if you control the server and 100% of the clients, but usually it is.

Imagine a client defines a base URI (your server.url) and then builds the final URIs using that and the path property of the desired operation. If they're using a different server.url (for tests or maybe because they're using a different deployment of the HTTP API), then their functionality will break.

Fresa commented 6 months ago

Imagine a client defines a base URI

Could you elaborate what you mean by that?