Giters

OpenAPITools / openapi-diff

Utility for comparing two OpenAPI specifications.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Servers.Url are not considered when path changes

Fresa opened this issue · comments

commented

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

commented

@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.

commented

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

commented

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.

commented

Imagine a client defines a base URI

Could you elaborate what you mean by that?