Skip to content

Fix #364: render parameter notes correctly in HtmlRender - #943

Open
Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:fix/364-htmlrender-notes
Open

Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:fix/364-htmlrender-notes

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 15, 2026 •

Copy link
Copy Markdown

Fixes #364.

Problem

The Notes row for a changed parameter in the HTML report was built from the same parameter object on both sides (the original report in #364), so the struck-through old notes always showed the new description. That one-liner was corrected by #547, but the issue stayed open because the fix never referenced it, and the row still had a defect on the same lines: it inserted the raw description values without a null guard. When a parameter gains a description it did not have before, j2html renders the null value as the literal text null, producing <del class="comment">null</del> change into <span class="comment">new description</span>.

Fix

Guard both values in li_changedParam exactly like the neighboring li_addParam, li_missingParam and li_deprecatedParam rows do: emit an empty element when a description is absent.

Verification

  • Added issue-364-param-notes-1.json / issue-364-param-notes-2.json where one parameter changes its description and another gains one.
  • New regression tests in HtmlRenderTest assert the old description is struck through (<del class="comment">Number of pets returned</del>), the new one is shown next to it, and no null text appears when a parameter gains notes.
  • mvnw -pl core,cli test: build success, all tests pass.

Note: #937 also touches HtmlRender.java (operation Description section around line 203 and a new helper at the end of the file); this change is in the li_changedParam Notes branch (around line 561) and does not overlap those hunks.

Signed-off-by: Inf1mum vadimlazuk5@gmail.com


Summary by cubic

Fixes rendering of parameter notes in the HTML report so changed parameters show the correct old and new descriptions, and no literal null text appears when a parameter gains a description.

  • Guards both old and new description values in li_changedParam the same way neighboring rows do, emitting an empty element when a description is absent.
  • Adds regression tests covering a changed description and a newly added description.

Written for commit 538f9a4. Summary will update on new commits.

View guided diff

For a changed parameter, the Notes row in the HTML report is built from
the old and new parameter descriptions. The original bug reported in
OpenAPITools#364 (both sides taken from the new parameter, so the notes always
showed the new description) was already corrected, but the row still
inserted the raw values: when a parameter gains a description it did
not have before, j2html renders the null value as the literal text
"null" in the struck-through old notes.

Guard both values like the neighboring add, delete and deprecated
parameter rows do, emitting an empty element when a description is
absent, and add regression tests asserting that the old description is
struck through and the new one shown for a changed parameter.

Fixes OpenAPITools#364.

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="core/src/test/java/org/openapitools/openapidiff/core/output/HtmlRenderTest.java">

<violation number="1" location="core/src/test/java/org/openapitools/openapidiff/core/output/HtmlRenderTest.java:63">
P3: The new tests never exercise a removed description, so the new-side null guard in `li_changedParam` is untested. Add a fixture where a parameter's description is deleted in the right spec and assert no `null` is rendered. The second test also re-renders the same diff as the first, so consider folding its `doesNotContain(">null<")` check into the first test.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

}

@Test
public void issue364_renderDoesNotShowNullWhenParameterGainsNotes() {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The new tests never exercise a removed description, so the new-side null guard in li_changedParam is untested. Add a fixture where a parameter's description is deleted in the right spec and assert no null is rendered. The second test also re-renders the same diff as the first, so consider folding its doesNotContain(">null<") check into the first test.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At core/src/test/java/org/openapitools/openapidiff/core/output/HtmlRenderTest.java, line 63:

<comment>The new tests never exercise a removed description, so the new-side null guard in `li_changedParam` is untested. Add a fixture where a parameter's description is deleted in the right spec and assert no `null` is rendered. The second test also re-renders the same diff as the first, so consider folding its `doesNotContain(">null<")` check into the first test.</comment>

<file context>
@@ -43,4 +43,33 @@ public void issue865_renderWithShowAllChangesDoesNotFailWhenSchemaIsNullButExamp
+  }
+
+  @Test
+  public void issue364_renderDoesNotShowNullWhenParameterGainsNotes() {
+    HtmlRender render = new HtmlRender();
+    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
</file context>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HtmlRender: Notes of Parameters shows always the new description

1 participant