Fix #893: render changed security requirements in MarkdownRender
Fixes #893
Problem
When the only change between two specs is inside a securitySchemes definition (e.g. OAuth2 flow authorizationUrl/tokenUrl), the diff model correctly attaches ChangedSecurityRequirements to the affected operation, but MarkdownRender only renders Operation ID / Parameters / Request / Return Type sections. The result is a changed-operation header with no explanation, followed by "API changes broke backward compatibility" (as diagnosed by @DrSatyr in the issue).
Root cause
MarkdownRender.listEndpoints(...) never renders ChangedOperation#getSecurityRequirements() — the model has the data, the renderer drops it.
What changed
MarkdownRender now renders a Security Requirements section for changed operations when operation.resultSecurityRequirements().isDifferent():
- added / deleted security requirements (scheme names),
- changed requirements: scheme-level changes (
type,in,scheme,bearerFormat,openIdConnectUrl, scopes, description) and OAuth flow changes (authorizationUrl/tokenUrl/refreshUrl, old → new).
Repro (specs from the issue, '' → 'some_value' for authorizationUrl/tokenUrl)
Before:
### Company API (v V0)
---
#### What's Changed
---
##### `POST` /users
#### Result
---
API changes broke backward compatibility
After:
### Company API (v V0)
---
#### What's Changed
---
##### `POST` /users
###### Security Requirements:
Changed security requirement: `OAuth2`
* Changed authorizationCode flow:
* authorizationUrl: `` -> `some_value`
* tokenUrl: `` -> `some_value`
#### Result
---
API changes broke backward compatibility
Breaking-ness decision
No model changes: the compatibility verdict keeps following the diff model. ChangedOAuthFlow marks OAuth2 URL changes as incompatible only when the incompatible.security.scheme.oauth2.auth.url.changed / ...token.url.changed / ...refresh.url.changed properties are enabled, and they are enabled by default by design since #552 (covered by OAuthFlowBCTest). So by default the output still reports the change as breaking — but now it shows why. When a user disables those properties, the same change renders as "API changes are backward compatible" while still listing the URL changes. This is covered by the new tests.
Renderers not touched
AsciidocRender and ConsoleRender have the same gap (no security section at all); JsonRender serializes the whole diff model and is unaffected. I deliberately did not refactor those in this PR — happy to follow up if desired.
Tests
New fixtures issue-893-oauth-1.yaml / issue-893-oauth-2.yaml (minimal version of the issue's specs, differing only in the OAuth2 flow URLs) and two tests in MarkdownRenderTest:
issue893_renderChangedSecuritySchemeDetailsInMarkdown— default config: security section rendered with the actual URL changes; result follows the model (incompatible).issue893_securitySchemeUrlChangeIsCompatibleWhenConfigDisabled— with the twoincompatible.security.scheme.oauth2.*properties disabled: diff is compatible, output says "API changes are backward compatible" and still renders the URL changes.
mvn -pl core test: 272 tests, 0 failures.
Summary by cubic
Fixes the Markdown renderer so changed security requirements (for example, OAuth2 flow URL updates) are now explained under a Security Requirements section, instead of showing only a changed-operation header with no detail.
- Renders added and deleted security requirements with their scopes, plus nested changes: schemes added to or removed from a changed requirement, scheme-level changes (type, location, scheme, bearer format,
openIdConnectUrl, scopes, description), and OAuth flow URLs. - Leaves the compatibility verdict untouched: it still follows the diff model, so OAuth2 URL changes remain breaking by default but now show why.
- Adds tests covering default breaking output and the case where the OAuth2 URL compatibility properties are disabled, using fixtures that follow the OpenAPI security-requirement scope rules.