swagger-api / swagger-api/swagger-core

[Bug]: @ArraysSchema applied on a stream property results in object type in OAS 3.1

Open
#5,013 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog Bug
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

@ArraysSchema applied on a stream property results in object type in OAS 3.1

Description of the problem/issue

We are using the springdoc with the swagger-core dependency. Once we switched from OpenApi 3.0 to 3.1 the Stream property of a POJO model is described as object instead of an array even if the @ArraySchema is applied to that property.

Affected Version

2.2.40

Earliest version the bug appears in (if known): we found it in 2.2.36.

Steps to Reproduce

Use this POJO model with a Stream property, while generating OAS 3.1:

@Getter
@Setter
public class ModelWithStream {

  @ArraySchema(schema = @Schema(implementation = Greeting.class))
  private Stream<Greeting> greetings;
}

Expected Behavior

The OAS 3.1 should contain this definition in components.schemas. The greetings property should be generated as a type array.

"ModelWithStream": {
  "type": "object",
  "properties": {
    "greetings": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Greeting"
      }
    }
  }
}

Actual Behavior

The greetings property is generated as a type object with the Stream.parallel property exposed in the schema.

"ModelWithStream": {
  "type": "object",
  "properties": {
    "greetings": {
      "type": "object",
      "items": {
        "$ref": "#/components/schemas/Greeting"
      },
      "properties": {
        "parallel": {
          "type": "boolean"
        }
      }
    }
  }
}

Logs / Stack Traces

N/A.

Additional Context

The expected model is generated when switching springdoc back to generate the OAS 3.0 version.

Checklist

  • I have searched the existing issues and this is not a duplicate.
  • I have provided sufficient information for maintainers to reproduce the issue.

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 OAS 3.1 generation with the ModelWithStream POJO and its Stream property annotated with @ArraySchema. Compare the generated components.schemas output with the OAS 3.0 result; done means greetings is an array whose items reference Greeting rather than an object exposing Stream.parallel.

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
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.