swagger-api / swagger-api/swagger-ui

Customizing wrapComponents operation when not using $ref to include docs does not show customizations on page load

Open
#9,247 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

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:
Screenshot 2023-09-25 at 10 34 25 AM

  • 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.