swagger-api / swagger-api/swagger-parser

[OpenAPI v3.1] Arrays now (incorrectly?) parse to JsonSchema rather than ArraySchema

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

In attempted to use swagger-codegen to read a 3.1.0 schema vs a 3.0.x schema, a notable change has occurred in how arrays are handled.

For example when provided the following path:

  /pets:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '204':
          description: 'No Content'

This parses to an ArraySchema in 3.0.x, but now parses to JsonSchema in 3.1.0. This could be intentional, as it sounds like some changes occurred in the structure of these objects for 3.1.0, but I'm not yet sure. I'm already multiple layers deep from my organisation, and our change will be to use 3.0.x for the time being, but leaving a report here.

swagger-codegen relies on this ArraySchema usage. The resultant codegen defaults to Object instead.

Example displaying this issue: https://github.com/dominic-jones/swagger-parser/commit/bec6fab4e4458e4294b97df488139d70261136f7

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 YAML example from the issue against OpenAPI 3.0.x and 3.1.0, then inspect the behavior shown in commit bec6fab4e4458e4294b97df488139d70261136f7. The issue names no source file or test; done requires determining whether the 3.1.0 ArraySchema-to-JsonSchema result is intentional and documenting or correcting the parser behavior accordingly.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.