Skip to content

#215 bring HtmlRender to markdown report parity - #966

Open
Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:fix/215-html-render-parity
Open

Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:fix/215-html-render-parity

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 18, 2026 •

Copy link
Copy Markdown

Fixes #215

HtmlRender reported far less than MarkdownRender. The HTML report now includes: the spec title/version header, the Result/compatibility summary, request-body descriptions, full schema details (new/required/optional/deleted/changed properties with types and descriptions, enum value changes, items, oneOf), response reason phrases and response headers. The default mode previously rendered nothing for compatible schema changes — the exact reported bug — and now renders full details.

10/10 HtmlRender tests (7 new); full ./mvnw verify green. MarkdownRender untouched.


Summary by cubic

Brings HtmlRender to parity with MarkdownRender so the HTML report no longer silently omits compatible schema changes.

  • Adds the spec title/version header, a Result section with the backward-compatibility summary, and request-body descriptions.
  • Reports full schema details: added/deleted/changed properties with types and descriptions, new required/optional properties, enum value changes, items, and oneOf changes.
  • Includes HTTP reason phrases for status codes and new/deleted/changed response headers.
  • Fixes the default mode rendering nothing for compatible schema changes.

Migration

  • None required. HtmlRender output format changes; existing HTML consumers may need to re-verify assertions against the expanded content.

Written for commit 35ced90. Summary will update on new commits.

View guided diff

…tion and result in HtmlRender

Align HtmlRender with MarkdownRender output coverage:
- spec title and version in the page header
- Result section with backward compatibility summary
- schema change details: new required/optional properties, added/deleted
  properties with type and description, changed property old -> new type
  and description, enum value changes, items changes, oneOf schema changes
- response HTTP reason phrase and new/deleted/changed response headers
- changed request body description

Signed-off-by: Inf1mum <[email protected]>

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

5 issues found across 2 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:68">
P2: This assertion only checks the formatting prefix `(v `, so the test passes even when the spec title or version is omitted. Assert the fixture’s expected `Swagger Petstore (v 1.0.0)` text.</violation>

<violation number="2" location="core/src/test/java/org/openapitools/openapidiff/core/output/HtmlRenderTest.java:93">
P2: This test never exercises an added property despite its name: both fixtures differ only by deleting `childProperty`, and both assertions check that deletion. Add an added-property fixture and assertion, or rename the test to describe deletion coverage.</violation>
</file>

<file name="core/src/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java">

<violation number="1" location="core/src/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java:350">
P3: Numeric response codes absent from `HttpStatus`'s phrase map render with a literal `null` (for example, `418 null`). Append the phrase only when the lookup returns one.</violation>

<violation number="2" location="core/src/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java:494">
P2: Added object and array properties are shown only as a single type/description line, so their nested fields and enum values are missing from the HTML report. Recurse into each added schema, as `MarkdownRender` does.</violation>

<violation number="3" location="core/src/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java:585">
P2: Added `oneOf` variants are rendered only as a name and type, so their properties and nested schema details are missing from HTML reports. Render the added `Schema` recursively, matching `MarkdownRender`'s `oneOfSchema` implementation.</violation>
</file>

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

View guided diff | Re-trigger cubic

}

@Test
public void issue215_renderReportsAddedAndDeletedProperties() {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: This test never exercises an added property despite its name: both fixtures differ only by deleting childProperty, and both assertions check that deletion. Add an added-property fixture and assertion, or rename the test to describe deletion coverage.

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 93:

<comment>This test never exercises an added property despite its name: both fixtures differ only by deleting `childProperty`, and both assertions check that deletion. Add an added-property fixture and assertion, or rename the test to describe deletion coverage.</comment>

<file context>
@@ -43,4 +43,82 @@ public void issue865_renderWithShowAllChangesDoesNotFailWhenSchemaIsNullButExamp
+  }
+
+  @Test
+  public void issue215_renderReportsAddedAndDeletedProperties() {
+    String html = render("missing_property_1.yaml", "missing_property_2.yaml");
+    assertThat(html).contains("Deleted property: childProperty");
</file context>

@Test
public void issue215_renderReportsSpecTitleVersionAndResultSection() {
String html = render("petstore_v2_1.yaml", "petstore_v2_2.yaml");
assertThat(html).contains("(v ");

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: This assertion only checks the formatting prefix (v , so the test passes even when the spec title or version is omitted. Assert the fixture’s expected Swagger Petstore (v 1.0.0) text.

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 68:

<comment>This assertion only checks the formatting prefix `(v `, so the test passes even when the spec title or version is omitted. Assert the fixture’s expected `Swagger Petstore (v 1.0.0)` text.</comment>

<file context>
@@ -43,4 +43,82 @@ public void issue865_renderWithShowAllChangesDoesNotFailWhenSchemaIsNullButExamp
+  @Test
+  public void issue215_renderReportsSpecTitleVersionAndResultSection() {
+    String html = render("petstore_v2_1.yaml", "petstore_v2_2.yaml");
+    assertThat(html).contains("(v ");
+    assertThat(html).contains("Result");
+    assertThat(html).contains("API changes broke backward compatibility");
</file context>
Suggested change
assertThat(html).contains("(v ");
assertThat(html).contains("Swagger Petstore (v 1.0.0)");

valueLine(
output,
String.format(
"Added '%s' %s (%s)", key, discriminator, resolveTypeQuietly(sub))

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: Added oneOf variants are rendered only as a name and type, so their properties and nested schema details are missing from HTML reports. Render the added Schema recursively, matching MarkdownRender's oneOfSchema implementation.

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/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java, line 585:

<comment>Added `oneOf` variants are rendered only as a name and type, so their properties and nested schema details are missing from HTML reports. Render the added `Schema` recursively, matching `MarkdownRender`'s `oneOfSchema` implementation.</comment>

<file context>
@@ -394,45 +505,121 @@ private void incompatibilities(final LiTag output, final ChangedSchema schema) {
+                  valueLine(
+                      output,
+                      String.format(
+                              "Added '%s' %s (%s)", key, discriminator, resolveTypeQuietly(sub))
+                          .trim()));
+    }
</file context>

}
listDiff(output, "enum value", schema.getEnumeration());
properties(
output, prefix, "Added property", schema.getIncreasedProperties(), schema.getContext());

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: Added object and array properties are shown only as a single type/description line, so their nested fields and enum values are missing from the HTML report. Recurse into each added schema, as MarkdownRender does.

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/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java, line 494:

<comment>Added object and array properties are shown only as a single type/description line, so their nested fields and enum values are missing from the HTML report. Recurse into each added schema, as `MarkdownRender` does.</comment>

<file context>
@@ -373,19 +479,24 @@ private void allChanges(final LiTag output, final ChangedSchema schema) {
     }
+    listDiff(output, "enum value", schema.getEnumeration());
+    properties(
+        output, prefix, "Added property", schema.getIncreasedProperties(), schema.getContext());
+    properties(
+        output, prefix, "Deleted property", schema.getMissingProperties(), schema.getContext());
</file context>

if (code.equals("default") || code.matches("[1-5]XX")) {
return code;
}
return code + " " + HttpStatus.getReasonPhrase(Integer.parseInt(code));

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: Numeric response codes absent from HttpStatus's phrase map render with a literal null (for example, 418 null). Append the phrase only when the lookup returns one.

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/main/java/org/openapitools/openapidiff/core/output/HtmlRender.java, line 350:

<comment>Numeric response codes absent from `HttpStatus`'s phrase map render with a literal `null` (for example, `418 null`). Append the phrase only when the lookup returns one.</comment>

<file context>
@@ -297,29 +343,89 @@ private UlTag ul_response(ChangedApiResponse changedApiResponse) {
+    if (code.equals("default") || code.matches("[1-5]XX")) {
+      return code;
+    }
+    return code + " " + HttpStatus.getReasonPhrase(Integer.parseInt(code));
+  }
+
</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 reports far less informations than MarkdownRender

1 participant