swagger-api / swagger-api/swagger-parser

Unable to Parse Referenced ArraySchema in Swagger File

Open
#2,065 2 comments 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

Description:
The current swagger-parser (version 2.1.21) fails to parse the referenced ArraySchema in the provided Swagger YAML file. When attempting to resolve the schema, the parser returns a null value for $ref and ignores the object properties defined within the array schema, which leads to incomplete parsing. It captures addresses field as ArraySchema but failed to capture it's properties.

Steps to Reproduce:

  • Use the provided Swagger YAML file containing a referenced ArraySchema.
  • Run the Swagger parser with the specified configurations and dependencies.
  • Inspect the parsed output and notice the null values for properties within the ArraySchema.

Expected Behavior:
The Swagger parser should successfully parse and resolve all referenced schemas, including ArraySchema, providing complete and accurate schema definitions.

YAML File:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: Created

components:
  schemas:
    UserInput:
      type: object
      properties:
        username:
          type: string
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        zip:
          type: string

Dependency used:

<dependency>
      <groupId>io.swagger.parser.v3</groupId>
      <artifactId>swagger-parser</artifactId>
      <version>2.1.21</version>
  </dependency>

Swagger parser configurations:

  OpenAPIV3Parser parser = new OpenAPIV3Parser();
    ParseOptions options = new ParseOptions();
    options.setResolve(true);
    options.setResolveFully(true);
    options.setResolveRequestBody(true);
    options.setResolveCombinators(true);
    io.swagger.v3.oas.models.OpenAPI swagger = parser.read("api-specification/sample-api.yaml", null, options);
    Map<String, PathItem> paths = swagger.getPaths();
    System.out.println(paths);

Output (with unresolved ArraySchema):

 class Paths {
    {/users=class PathItem {
        summary: null
        description: null
        get: null
        put: null
        post: class Operation {
            tags: null
            summary: Create a new user
            description: null
            externalDocs: null
            operationId: null
            parameters: null
            requestBody: class RequestBody {
                description: null
                content: class Content {
                    {application/json=class MediaType {
                        schema: 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: {username=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
                                    }
                                }, addresses=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
                            }
                        }
                        examples: null
                        example: null
                        encoding: null
                    }}
                }
                required: true
            }
            responses: class ApiResponses {
                {201=class ApiResponse {
                    description: Created
                    headers: null
                    content: null
                    links: null
                    extensions: null
                    $ref: null
                }}
                extensions: null
            }
            callbacks: null
            deprecated: null
            security: null
            servers: null
        }
        delete: null
        options: null
        head: null
        patch: null
        trace: null
        servers: null
        parameters: null
        $ref: null
    }}
}

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

Start by reproducing the issue with the sample OpenAPI YAML and the OpenAPIV3Parser configuration shown in the report. Inspect how the referenced Address schema is handled under UserInput.addresses when resolve and resolveFully are enabled. Done means the array items retain the referenced Address properties instead of producing an incomplete ArraySchema.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.