Render changed operation description in HtmlRender

IN
6h ago
+282-0

Summary

Fixes #857.

When an operation's description changes, the diff core detects it (OperationDiff sets ChangedOperation#description, DiffResult.METADATA), and the operation is listed under "What's Changed" - but neither HtmlRender nor MarkdownRender emitted the changed description, so the report showed a changed operation with no visible detail.

Change

HtmlRender: adds a Description section to the operation's detail list (ul_detail), following the exact j2html pattern used for the other operation-level sections (Operation ID, Parameters, Request, Response): a li with an h3 heading wrapping a ul.change.description item. The old description is struck through (del, comment class) and the new one shown next to it ("change into"), mirroring how the changed parameter notes (li_changedParam) are already rendered. Rendered for both the default and showAllChanges renderers, since the operation appears in the changed list in both cases.

MarkdownRender: had the same gap, fixed symmetrically with the existing metadata(...) helper, so it respects the showChangedMetadata flag exactly like the operation summary does:

  • with showChangedMetadata: Changed description: old -> new
  • without: just the new description as a blockquote

Console/Asciidoc renderers also do not show operation description changes today; left out of this PR to keep the diff focused on the reported issue (can follow up if wanted).

Repro from the issue

Tested with the two specs attached to the issue (sample-api_3.47.0_ALL.json / sample-api_3.48.0_ALL.json, only the CAN operation description and the version differ), copied as issue-857-operation-description-1.json / issue-857-operation-description-2.json. Before: the changed operation rendered as POST /sample-api/{id}/actions/CAN with an empty detail list. After, the HTML report contains:

<li>
  <h3>Description</h3>
  <ul class="change description">
    <li>Changed description: <del class="comment">Sample description</del> change into <span class="comment">Sample description changed</span></li>
  </ul>
</li>

Tests

  • HtmlRenderTest#issue857_renderShowsChangedOperationDescription (default renderer): asserts the old -> new description snippet (del with the old text, span with the new text) is present.
  • HtmlRenderTest#issue857_renderWithShowAllChangesShowsChangedOperationDescription (the showAllChanges=true constructor used in the issue).
  • MarkdownRenderTest#issue857_renderShowsChangedOperationDescription (with showChangedMetadata, asserting the old and new description are rendered).

mvn -pl core test: 273 tests, 0 failures; com.coveo:fmt-maven-plugin:check passes.

Note on coordination: open PRs #930 (media type examples) and #933 (security requirements in Markdown) touch the same renderer files, but at different locations - this change only adds the operation-description rendering path and does not overlap their lines.

Summary by cubic

Fixes #857: renders changed operation descriptions in HtmlRender and MarkdownRender reports so a changed operation no longer appears under "What's Changed" with empty detail.

The diff core already detected the description change, but neither renderer emitted it. HtmlRender now shows a Description section with the old description struck through next to the new one, and MarkdownRender renders the change through the existing metadata helper, respecting the showChangedMetadata flag. Tests assert the full old-to-new rendering in both renderers, covering default and showAllChanges modes.