swagger-api / swagger-api/swagger-core
enumsAsRef breaks @Schema behavior
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 7.5k
- Forks
- 2.3k
- Avg merge
- 18h 1m
- Merged PRs (30d)
- 10
Description
Given an example application:
public class TestApp {
public static void main(String[] args) {
io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true;
Map<String, Schema> schemaMap = ModelConverters.getInstance().readAll(MyClass.class);
System.out.println(schemaMap.toString());
}
public enum TestEnum {
VAL1, VAL2
}
public record MyClass(
TestEnum field1,
@io.swagger.v3.oas.annotations.media.Schema(deprecated = true) TestEnum field2
) {
}
}
The result is:
{MyClass=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: {field1=class Schema {
type: null
format: null
$ref: #/components/schemas/TestEnum
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
}, field2=class Schema {
type: null
format: null
$ref: #/components/schemas/TestEnum
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
}, TestEnum=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: true
discriminator: null
xml: null
}
}}
That is, the deprecated: true gets applied to the entire enum, instead of just the field.
Removing the line io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true; produces correct output (the deprecation only gets applied to the field) but, of course, the enum is not separately documented:
{MyClass=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: {field1=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
}
}, field2=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: true
discriminator: null
xml: null
}
}}
additionalProperties: null
nullable: null
readOnly: null
writeOnly: null
example: null
externalDocs: null
deprecated: null
discriminator: null
xml: null
}}
Desired outcome:
Using @Schema on an enum field when enumsAsRef==true should only apply that schema to the field, not the entire enum.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ModelResolver.enumsAsRef and the ModelConverters.readAll(MyClass.class) path shown in the example, then trace how @Schema(deprecated = true) is applied to an enum field and its referenced TestEnum schema. Reproduce the output with the provided TestApp, and consider the issue done when the deprecation remains on field2 without being copied to TestEnum while the enum is still separately documented.
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
- Clearly specified
- Newbie friendliness
- 48/100