swagger-api / swagger-api/swagger-ui

Enums being exploded everywhere when openapi version is 3.1.1 (correct in 3.0.0)

Open
#10,665 0 comments 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: [e.g. macOS] mac OS
  • Browser: [e.g. chrome, safari] chrome
  • Version: unsure
  • Method of installation: unsure
  • Swagger-UI version: unsure
  • Swagger/OpenAPI version: unsure
Content & configuration

Example Swagger/OpenAPI definition:

{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Generated server url"
    }
  ],
  "paths": {
    "/hello": {
      "get": {
        "tags": [
          "my-controller"
        ],
        "operationId": "hello",
        "parameters": [
          {
            "name": "request",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestWrapper"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/Wrapper"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MyEnum": {
        "type": "string",
        "enum": [
          "FOO",
          "BAR"
        ]
      },
      "RequestWrapper": {
        "type": "object",
        "properties": {
          "enumValue": {
            "$ref": "#/components/schemas/MyEnum"
          }
        }
      },
      "Wrapper": {
        "type": "object",
        "properties": {
          "enumValue": {
            "$ref": "#/components/schemas/MyEnum"
          }
        }
      }
    }
  }
}

I am testing using only https://swagger.io/tools/swagger-editor/ but I have encountered this locally as well.

Describe the bug you're encountering
To reproduce...

Steps to reproduce the behavior:

  1. Go to https://editor.swagger.io/
  2. Paste in the YAML above
  3. Notice that the enum is exploded in all types that have the enum as a field
  4. Change OAS version to 3.0.0 and the enum is no longer exploded everywhere but is rather referred to.
Expected behavior

I expected 3.1.0 to behave as well as 3.0.0 in terms of enums.

Screenshots
With 3.1.0
Image
With 3.0.0
Image
Additional context or thoughts

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 behavior in https://editor.swagger.io/ using the supplied definition, then compare the generated output for OpenAPI 3.1.0 and 3.0.0. Trace the Swagger UI rendering path for schemas referenced by enum-valued fields; done means 3.1.0 preserves the enum reference instead of expanding it in every containing type, with regression coverage for both versions.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.