swagger-api / swagger-api/swagger-ui

Property-level `title` keyword is silently dropped for OpenAPI 3.1 schemas

Open
#11,053 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • OS: All
  • Browser: All
  • Version: editor.swagger.io
  • Method of installation: None
  • Swagger-UI version: editor.swagger.io
  • Swagger/OpenAPI version: OpenAPI 3.0/3.1

Example Swagger/OpenAPI definition:

openapi: 3.1.0
info:
  title: Repro
  version: "1.0"
paths:
  /example:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: Example
              properties:
                plainField:
                  type: integer
                  format: int32
                  title: Only renders on OAS 3.0
                  description: Renders always.
                titledField:
                  type: integer
                  format: int32
                  title: Only renders on OAS 3.0
                  description: Renders always.
              required:
                - plainField
                - titledField
      responses:
        '200':
          description: OK

Describe the bug you're encountering

When a property inside an object schema has its own title keyword set, Swagger UI never renders it anywhere when the document is OpenAPI 3.1. The exact same schema, served as OpenAPI 3.0, renders the titles correctly.

To reproduce...

Steps to reproduce the behavior:

  1. Go to 'editor.swagger.io'
  2. Paste the example schema
  3. Compare title rendering (and lack thereof) between OAS 3.0 and 3.1
Expected behavior

A property's own title keyword should be displayed somewhere (as it is in the OAS 3.0).

Additional context or thoughts

This is distinct from the known $ref-sibling-keyword rendering (e.g., #9540) that changed in 3.1 due to stricter JSON schema adherence. There are zero $refs in the example, as the issue is entirely with property title rendering and has nothing to do with dereferencing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by loading the provided schema in editor.swagger.io and compare property-title rendering between OpenAPI 3.0 and 3.1. Trace the schema property rendering path, then verify that each property's own title is displayed for 3.1 while the existing 3.0 behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.