swagger-api / swagger-api/swagger-ui
Models using allOf break when deeply nested by $ref
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: Ubuntu
- Browser: Chrome
- Version: 92
- Method of installation: editor.swagger.io
- Swagger-UI version: 3.51.1
- Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration
Example Swagger/OpenAPI definition:
openapi: 3.0.0
info:
title: Test REST API
version: 1.0.0
components:
schemas:
TheOneWhichBreaks:
allOf:
- type: object
properties:
id:
type: string
- type: object
properties:
position:
type: integer
ReferringA:
type: object
properties:
theOneWhichBreaks:
$ref: "#/components/schemas/TheOneWhichBreaks"
ReferringB:
type: object
properties:
referringA:
$ref: "#/components/schemas/ReferringA"
HereBreaksToo:
type: object
properties:
referringB:
$ref: "#/components/schemas/ReferringB"
paths:
/works:
get:
tags:
- Test
summary: Shown as intended
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
referringA:
$ref: "#/components/schemas/ReferringA"
/breaks:
get:
tags:
- Test
summary: Isn't shown as intended
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
referringB:
$ref: "#/components/schemas/ReferringB"
Describe the bug you're encountering
A model combining other models with allOf doesn't show properly if there are 3 or more $ref usages on higher levels. In this case it usually has a value "string" or empty object.
To reproduce...
Steps to reproduce the behavior:
- Go to editor.swagger.io
- Paste the definition I left above
- Compare responses of two paths. Notice how
TheOneWhichBrakesmodel shows - You also can check a model called "HereBreaksToo"
Expected behavior
Referenced models should render their type despite of referencing depth.
Screenshots



Additional context or thoughts
I've managed to reproduce the bug using different environments:
swagger-ui-express
swagger-ui-express@4.1.6
swagger-ui-dist@3.51.1
WebStorm
Plugin OpenAPI Specifications 202.7319.8
editor.swagger.io
There is a feature here. It reproduces during the first render. But there is an algorithm which makes it display properly:
- Expand the
/workspath. It always showsTheOneWhichBrakesmodel properly. You also can just expandTheOneWhichBrakesmodel itself - Expand the
/breakspath. It will show you the broken view - Make a meaningless change in the editor. You can add an extra line in the end of the definition
- See how
/breaksis rendered as intended now
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in editor.swagger.io with the supplied OpenAPI definition and compare the /works and /breaks responses, including the HereBreaksToo model. Reproduce the first-render failure and confirm that deeply referenced allOf models render their types consistently after the fix.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100