swagger-api / swagger-api/swagger-ui
Customizing wrapComponents operation when not using $ref to include docs does not show customizations on page load
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
When docs are generated without using $ref for including each endpoints docs using wrapComponents to show, for example a Beta tag, does not work as expected.
- Docs are generated with $ref, the beta tag will show on page load of the docs (expected).
- Doc objects are directly in the json rather than in a $ref, you have to click the item in the docs before the Beta tag will show (unexpected).
This is the code used to do add the Beta tag:
return {
wrapComponents: {
operation: (Ori, system) => (props) => {
const isBeta = !!props.operation.get("op").get("x-beta")
if (isBeta) {
return system.React.createElement(
"div",
{style:{position: 'relative', overflow: 'hidden'}},
[
system.React.createElement('div', { className: 'beta' }, 'beta'),
system.React.createElement(Ori, props)
]
)
}
return system.React.createElement(Ori, props)
}
}
}
When I manually create the docs using $ref, it works as expected (the beta tag will show on load of the docs):
{
"openapi": "3.0.1",
"info": {
"title": "Some Title",
"description": "Some description...",
"contact": {
"name": "Support Name",
"email": "my@email.com"
},
"version": "2.0"
},
"servers": [
{
"url": "/api/v2"
}
],
"paths": {
"/api/path": {
"$ref": "./some-api-docs.json"
}
},
"components": {
"schemas": { ... },
"securitySchemes": { ... }
}
}
When I automatically generate the docs with something like https://github.com/go-openapi/swag which generates docs from godoc notation, it does not work as expected: (you have to click the item in the docs before the Beta tag will actually show).
This is how the doc json is produced:
{
"openapi": "3.0.1",
"info": {
"title": "Some Title",
"description": "Some description...",
"contact": {
"name": "Support Name",
"email": "my@email.com"
},
"version": "2.0"
},
"servers": [
{
"url": "/api/v2"
}
],
"paths": {
"/api/path": {
"get": {
"tags": [
"tag"
],
"summary": "some summary",
"description": "some description",
"operationId": "some-id",
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"x-beta": true
}
}
},
"components": {
"schemas": { ... },
"securitySchemes": { ... }
}
}
Both of the API docs have the x-beta set to true, but only the one using $ref shows on load:
- OS: macOS
- Browser: Chrome, Safari, Firefox (all)
- Version: latest
- Method of installation: standalone
- Swagger-UI version: 5.7.2 (also test other previous versions with same results)
- Swagger/OpenAPI version: OpenAPI 3.0.1
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
Reproduce the issue using the documented wrapComponents operation customization and the two OpenAPI 3.0.1 examples: one with path-level $ref and one with inline operations. Start by comparing operation rendering during initial page load versus after expanding an item; done means the x-beta customization appears immediately for both document shapes in Swagger UI 5.7.2.
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