Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #1067: Add basic support for examples as well as example #1065

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

jceipek
Copy link

@jceipek jceipek commented Dec 21, 2024

This PR fixes the following bug, #1067: the examples keyword is not supported at all in some contexts, which causes some response fields to be shown with a generic example even though a schema-supplied example is available.

In cases where it wasn't supported at all, we instead now pick the first example from examples, which is a valuable incremental improvement and matches the behavior of https://editor-next.swagger.io/.

Given the following minimal, valid spec:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Test API",
    "version": "0.0.1",
    "description": "Minimal test"
  },
  "paths": {
    "/api/test": {
      "post": {
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "list_field": {
                      "description": "List of Strings",
                      "examples": [["Bug: missing from output"]],
                      "items": { "type": "string" },
                      "type": "array"
                    },
                    "list_field_single_example": {
                      "description": "List of Strings single example",
                      "example": ["Deprecated but included in output"],
                      "items": { "type": "string" },
                      "type": "array"
                    },
                    "string_field": {
                      "description": "String Field",
                      "examples": ["Included in output", "Missing from output since only one example is displayed"],
                      "type": "string"
                    }
                  },
                  "required": [
                    "list_field",
                    "string_field"
                  ],
                  "title": "Demo",
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}

Before this PR, the example response was:

{
  "list_field": [
    "string"
  ],
  "list_field_single_example": [
    "Deprecated but included in output"
  ],
  "string_field": "Included in output"
}

Note [ "string" ] under list_field.

Now the example response is:

{
  "list_field": [
    "Bug: missing from output"
  ],
  "list_field_single_example": [
    "Deprecated but included in output"
  ],
  "string_field": "Included in output"
}

Note [ "Bug: missing from output" ] under list_field.

@jceipek jceipek changed the title Add support for examples as well as example Add basic support for examples as well as example Dec 21, 2024
@jceipek jceipek changed the title Add basic support for examples as well as example Fix #1067: Add basic support for examples as well as example Dec 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant