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

[4.0 regression] ref-properties get generated as $ref instead of allOf [ { $ref ...} ] #2097

Closed
Felk opened this issue Dec 6, 2024 · 2 comments

Comments

@Felk
Copy link

Felk commented Dec 6, 2024

I have the following model:

public record MyModel(
    @Schema(title = "Valid From", description = "Start timestamp this entity is valid from")
    Instant validFrom,
    // ...
) {}

Starting with smallrye-open-api 4.0 (I tested 4.0.4), this produces the following yaml:

"MyModel" : {
  "type" : "object",
  "properties" : {
    "validFrom" : {
      "title" : "Valid From",
      "description" : "Start timestamp this entity is valid from",
      "type" : "string",
      "$ref" : "#/components/schemas/Instant"
    },

The OpenAPI generated with smallrye-open-api-core:jar:3.13.0 was this:

"MyModel" : {
  "type" : "object",
  "properties" : {
    "validFrom" : {
      "title" : "Valid From",
      "description" : "Start timestamp this entity is valid from",
      "type" : "string",
      "allOf" : [ {
        "$ref" : "#/components/schemas/Instant"
      } ]
    },

The latter looks like a well-formed OpenAPI to me. However, the former appears to violate the OpenAPI 3.1 spec, see swagger-api/swagger-parser#2036 (comment).

[RefObject] cannot be extended with additional properties and any properties added SHALL be ignored.

Right now, this change causes any additional fields, like title and description in this case, to be lost by tooling, e.g. as described in swagger-api/swagger-parser#2036 (comment).

@MikeEdgar
Copy link
Member

The schema is somewhat of a special case object in OpenAPI 3.1 since it is now essentially just JSON Schema draft 2020-12 and the RefObject limitation no longer applies. See the fixed fields for components [1]. Schema does not allow a "Reference Object" like the others because it is now JSON Schema.

[1] https://spec.openapis.org/oas/v3.1.0.html#fixed-fields-5

@Felk
Copy link
Author

Felk commented Dec 9, 2024

Thanks for the clarification! Good to know, As I understand, this means that the 3.1 schema is valid and fields like title or description should not be lost. In that case, this seems to just be a bug in swagger-parser. I'll close this issue then in favor of swagger-api/swagger-parser#2036

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

No branches or pull requests

2 participants