Repository navigation
Changes reported in operations but only securityScheme changed #893
Description
I am using
testImplementation("org.openapitools.openapidiff:openapi-diff-core:2.1.6") {
exclude(group = "io.swagger.core.v3", module = "swagger-core")
exclude(group = "io.swagger.core.v3", module = "swagger-models")
exclude(group = "io.swagger.core.v3", module = "swagger-annotations")
}
Given the two API docs to compare where the only change is in authorizationUrl ('' vs. 'some_value') and tokenUrl ('' vs. 'some_value').
First file
components:
securitySchemes:
OAuth2:
bearerFormat: JWT
flows:
authorizationCode:
authorizationUrl: ''
tokenUrl: ''
in: header
scheme: bearer
type: oauth2
info:
title: Company API
version: V0
openapi: 3.1.0
paths:
/users:
post:
operationId: createUser
responses:
"201":
description: Created
security:
- OAuth2: []
servers:
- description: Default Server URL
url: /api/
Second file
components:
securitySchemes:
OAuth2:
bearerFormat: JWT
flows:
authorizationCode:
authorizationUrl: 'some_value'
tokenUrl: 'some_value'
in: header
scheme: bearer
type: oauth2
info:
title: Company API
version: V0
openapi: 3.1.0
paths:
/users:
post:
operationId: createUser
responses:
"201":
description: Created
security:
- OAuth2: []
servers:
- description: Default Server URL
url: /api/
The resulting error message is misleading as the issue is not directly related to any concrete endpoint. This took me quite a while to narrow this down to this difference.
So it would be nice to have a more suitable error message.
org.opentest4j.AssertionFailedError: [### Company API (v V0)
---
#### What's Changed
---
##### `POST` /users
#### Result
---
API changes broke backward compatibility
]
Activity
DrSatyr commentedon May 7, 2026
I can reproduce the root cause from the current code path.
The OAuth flow URL change is detected correctly by the diff model:
ChangedOAuthFlowmarksauthorizationUrl,tokenUrl, andrefreshUrlchanges as changed/incompatible depending on config.ChangedSecurityRequirements.The misleading output comes from the markdown renderer.
MarkdownRenderprints a changed operation header, but only renders these operation detail sections:It does not render
ChangedOperation#getSecurityRequirements(), so a security-scheme-only change leaves the operation listed with no explanation before the final “API changes broke backward compatibility” result.A focused fix would be to add security requirement rendering to
MarkdownRender, similar to the existing HTML renderer path, and include the changed scheme/flow details such as OAuth flow type and changedauthorizationUrl/tokenUrl.Existing
OAuthFlowBCTestcovers the compatibility result, but a regression test should also assert that markdown output for an OAuth flow URL change includes a security-related detail instead of only the endpoint heading.