From 797fe4c80b2d522bfd8b98b4b4e73b8ca843a90b Mon Sep 17 00:00:00 2001
From: Joshua <143388422+joshuablac@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:08:27 +0100
Subject: [PATCH] fix(json-schema-2020-12): render property schema title

What was wrong:
When an API describes a field and gives it a friendly name (a "title"),
for example a field called "nickname" titled "Pet nickname", Swagger UI
showed only "nickname" for OpenAPI 3.1 documents. The friendly name was
silently thrown away.

What this changes:
Swagger UI now shows the friendly name in italics next to the field name,
e.g. "nickname  Pet nickname". If the friendly name is just the field
name again (like "color" titled "color"), it is not repeated.

Also adds automated tests that check both cases.

Fixes #11053

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../components/keywords/Title/Title.jsx       | 17 +++++++++++++++-
 .../components/keywords/Title/_title.scss     |  6 ++++++
 .../json-schema-2020-12/schema-title.cy.js    | 20 +++++++++++++++++++
 .../features/json-schema-2020-12-title.yaml   |  6 ++++++
 4 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/src/core/plugins/json-schema-2020-12/components/keywords/Title/Title.jsx b/src/core/plugins/json-schema-2020-12/components/keywords/Title/Title.jsx
index 5cbec01ce29..f62f696b1fd 100644
--- a/src/core/plugins/json-schema-2020-12/components/keywords/Title/Title.jsx
+++ b/src/core/plugins/json-schema-2020-12/components/keywords/Title/Title.jsx
@@ -9,11 +9,26 @@ import { useFn } from "../../../hooks"
 
 const Title = ({ title = "", schema }) => {
   const fn = useFn()
+  const schemaTitle = fn.getTitle(schema, { lookup: "basic" })
   const renderedTitle = title || fn.getTitle(schema)
+  const hasSecondaryTitle =
+    typeof title === "string" &&
+    title !== "" &&
+    schemaTitle !== "" &&
+    !title.toLowerCase().includes(schemaTitle.toLowerCase())
 
   if (!renderedTitle) return null
 
-  return <strong className="json-schema-2020-12__title">{renderedTitle}</strong>
+  return (
+    <strong className="json-schema-2020-12__title">
+      {renderedTitle}
+      {hasSecondaryTitle && (
+        <span className="json-schema-2020-12__title-secondary">
+          {schemaTitle}
+        </span>
+      )}
+    </strong>
+  )
 }
 
 Title.propTypes = {
diff --git a/src/core/plugins/json-schema-2020-12/components/keywords/Title/_title.scss b/src/core/plugins/json-schema-2020-12/components/keywords/Title/_title.scss
index 5dcfdb5e228..106bc85bb90 100644
--- a/src/core/plugins/json-schema-2020-12/components/keywords/Title/_title.scss
+++ b/src/core/plugins/json-schema-2020-12/components/keywords/Title/_title.scss
@@ -12,6 +12,12 @@
     & .json-schema-2020-12-keyword__name {
       margin: 0;
     }
+
+    &-secondary {
+      margin-left: 10px;
+      font-weight: normal;
+      font-style: italic;
+    }
   }
 
   &-property {
diff --git a/test/e2e-cypress/e2e/features/plugins/json-schema-2020-12/schema-title.cy.js b/test/e2e-cypress/e2e/features/plugins/json-schema-2020-12/schema-title.cy.js
index 867178ce61b..2889b2d8979 100644
--- a/test/e2e-cypress/e2e/features/plugins/json-schema-2020-12/schema-title.cy.js
+++ b/test/e2e-cypress/e2e/features/plugins/json-schema-2020-12/schema-title.cy.js
@@ -18,4 +18,24 @@ describe("JSON Schema 2020-12 title keyword", () => {
       .contains("Error")
       .should("exist")
   })
+
+  it("should render a title for schema properties", () => {
+    cy.visit(
+      "/?url=/documents/features/json-schema-2020-12-title.yaml&defaultModelsExpandDepth=2"
+    )
+      .get(".json-schema-2020-12-property")
+      .contains(".json-schema-2020-12__title", "nickname")
+      .contains("Pet nickname")
+      .should("exist")
+  })
+
+  it("should not repeat a property title that matches the property name", () => {
+    cy.visit(
+      "/?url=/documents/features/json-schema-2020-12-title.yaml&defaultModelsExpandDepth=2"
+    )
+      .get(".json-schema-2020-12-property")
+      .contains(".json-schema-2020-12__title", "color")
+      .find(".json-schema-2020-12__title-secondary")
+      .should("not.exist")
+  })
 })
diff --git a/test/e2e-cypress/static/documents/features/json-schema-2020-12-title.yaml b/test/e2e-cypress/static/documents/features/json-schema-2020-12-title.yaml
index 63d82fc9f00..eec95c28a57 100644
--- a/test/e2e-cypress/static/documents/features/json-schema-2020-12-title.yaml
+++ b/test/e2e-cypress/static/documents/features/json-schema-2020-12-title.yaml
@@ -96,6 +96,12 @@ components:
           type: string
         tag:
           type: string
+        nickname:
+          type: string
+          title: Pet nickname
+        color:
+          type: string
+          title: color
     Pets:
       title: My Pets
       type: array