swagger-api / swagger-api/swagger-parser

$ref inside property missing

Open
#1,793 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
867
Forks
560
Avg merge
2d 21h
Merged PRs (30d)
7

Description

I have 2 components:

  1. ErrorArrayResponse with property errors which is an array of ApiResponseError
  2. ApiResponseError with 2 string properties, errorType and message.

The problem is that after parsing, ErrorArrayResponse shows errors as array, but without information that it is array of ApiResponseError. The $ref element after parsing is null.

I'm using io.swagger.parser.v3:swagger-parser:2.1.2

api-docs.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [],
  "security": [],
  "paths": {},
  "components": {
    "schemas": {
      "ApiResponseError": {
        "type": "object",
        "properties": {
          "errorType": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ErrorArrayResponse": {
        "required": [
          "errors"
        ],
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiResponseError"
            }
          }
        }
      }
    },
    "securitySchemes": {}
  }
}

code to execute (kotlin)

    val result = OpenAPIParser().readLocation("api-docs.json", null, null)
    val openApi = result.openAPI
    println(openApi.components)

Debug output

14:30:01.966 [main] DEBUG io.swagger.v3.parser.OpenAPIV3Parser - Loaded raw data: {
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [],
  "security": [],
  "paths": {},
  "components": {
    "schemas": {
      "ApiResponseError": {
        "type": "object",
        "properties": {
          "errorType": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ErrorArrayResponse": {
        "required": [
          "errors"
        ],
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiResponseError"
            }
          }
        }
      }
    },
    "securitySchemes": {}
  }
}

print components output

class Components {
    schemas: {ApiResponseError=class ObjectSchema {
        class Schema {
            type: object
            format: null
            $ref: null
            description: null
            title: null
            multipleOf: null
            maximum: null
            exclusiveMaximum: null
            minimum: null
            exclusiveMinimum: null
            maxLength: null
            minLength: null
            pattern: null
            maxItems: null
            minItems: null
            uniqueItems: null
            maxProperties: null
            minProperties: null
            required: null
            not: null
            properties: {errorType=class StringSchema {
                class Schema {
                    type: string
                    format: null
                    $ref: null
                    description: null
                    title: null
                    multipleOf: null
                    maximum: null
                    exclusiveMaximum: null
                    minimum: null
                    exclusiveMinimum: null
                    maxLength: null
                    minLength: null
                    pattern: null
                    maxItems: null
                    minItems: null
                    uniqueItems: null
                    maxProperties: null
                    minProperties: null
                    required: null
                    not: null
                    properties: null
                    additionalProperties: null
                    nullable: null
                    readOnly: null
                    writeOnly: null
                    example: null
                    externalDocs: null
                    deprecated: null
                    discriminator: null
                    xml: null
                }
            }, message=class StringSchema {
                class Schema {
                    type: string
                    format: null
                    $ref: null
                    description: null
                    title: null
                    multipleOf: null
                    maximum: null
                    exclusiveMaximum: null
                    minimum: null
                    exclusiveMinimum: null
                    maxLength: null
                    minLength: null
                    pattern: null
                    maxItems: null
                    minItems: null
                    uniqueItems: null
                    maxProperties: null
                    minProperties: null
                    required: null
                    not: null
                    properties: null
                    additionalProperties: null
                    nullable: null
                    readOnly: null
                    writeOnly: null
                    example: null
                    externalDocs: null
                    deprecated: null
                    discriminator: null
                    xml: null
                }
            }}
            additionalProperties: null
            nullable: null
            readOnly: null
            writeOnly: null
            example: null
            externalDocs: null
            deprecated: null
            discriminator: null
            xml: null
        }
    }, ErrorArrayResponse=class ObjectSchema {
        class Schema {
            type: object
            format: null
            $ref: null
            description: null
            title: null
            multipleOf: null
            maximum: null
            exclusiveMaximum: null
            minimum: null
            exclusiveMinimum: null
            maxLength: null
            minLength: null
            pattern: null
            maxItems: null
            minItems: null
            uniqueItems: null
            maxProperties: null
            minProperties: null
            required: [errors]
            not: null
            properties: {errors=class ArraySchema {
                class Schema {
                    type: array
                    format: null
                    $ref: null
                    description: null
                    title: null
                    multipleOf: null
                    maximum: null
                    exclusiveMaximum: null
                    minimum: null
                    exclusiveMinimum: null
                    maxLength: null
                    minLength: null
                    pattern: null
                    maxItems: null
                    minItems: null
                    uniqueItems: null
                    maxProperties: null
                    minProperties: null
                    required: null
                    not: null
                    properties: null
                    additionalProperties: null
                    nullable: null
                    readOnly: null
                    writeOnly: null
                    example: null
                    externalDocs: null
                    deprecated: null
                    discriminator: null
                    xml: null
                }
            }}
            additionalProperties: null
            nullable: null
            readOnly: null
            writeOnly: null
            example: null
            externalDocs: null
            deprecated: null
            discriminator: null
            xml: null
        }
    }}
    responses: null
    parameters: null
    examples: null
    requestBodies: null
    headers: null
    securitySchemes: {}
    links: null
    callbacks: null
    pathItems: null
}

Swagger UI is showing ErrorArrayResonse with erorrs as array of ApiResponseError:
image

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

The reproduction enters through OpenAPIParser().readLocation using api-docs.json, with parsing handled by OpenAPIV3Parser; begin there and trace resolution of the array item's $ref. Reproduce the missing ApiResponseError reference and add a regression check showing that ErrorArrayResponse.errors retains that schema reference.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, kotlin
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 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.