feat: swagger2 add support for Schema.requiredMode (#372)

CHANGELOG.md

@@ -15,8 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - elevate nested properties to the parent type where members are annotated with `@JsonUnwrapped`
 
 ### `jsonschema-module-swagger-2`
+***NOTE: `io.swagger.core.v3:swagger-annotations` minimum version is now `2.2.5`!***
 #### Added
 - consider `@Schema(additionalProperties = ...)` attribute (only values `TRUE` and `FALSE`), when it is annotated on a type (not on a member)
+- consider `@Schema(requiredMode = REQUIRED)` in addition to deprecated `@Schema(required = true)`
 
 #### Fixed
 - avoid rounding error when taking over the value from `@Schema(multipleOf)`

jsonschema-generator-parent/pom.xml

@@ -140,7 +140,7 @@
         <version.jakarta.validation>3.0.2</version.jakarta.validation>
         <version.javax.validation>2.0.1.Final</version.javax.validation>
         <version.swagger-1.5>1.6.7</version.swagger-1.5>
-        <version.swagger-2>2.2.3</version.swagger-2>
+        <version.swagger-2>2.2.5</version.swagger-2>
         <!-- maven plugin runtime dependencies -->
         <version.classgraph>4.8.149</version.classgraph>
     </properties>

jsonschema-module-swagger-2/README.md

@@ -6,38 +6,39 @@ Module for the [jsonschema-generator](../jsonschema-generator) – deriving JSON
 ## Features
  1. From `@Schema(description = …)` on types in general, derive `"description"`.
  2. From `@Schema(title = …)` on types in general, derive `"title"`.
- 3. From `@Schema(subTypes = …)` on types in general, derive `"anyOf"` alternatives.
- 4. From `@Schema(anyOf = …)` on types in general (as alternative to `subTypes`), derive `"anyOf"` alternatives.
- 5. From `@Schema(name = …)` on types in general, derive the keys/names in `"definitions"`/`"$defs"`.
- 6. From `@Schema(description = …)` on fields/methods, derive `"description"`.
- 7. From `@Schema(title = …)` on fields/methods, derive `"title"`.
- 8. From `@Schema(implementation = …)` on fields/methods, override represented type.
- 9. From `@Schema(hidden = true)` on fields/methods, skip certain properties.
-10. From `@Schema(name = …)` on fields/methods, override property names.
-11. From `@Schema(ref = …)` on fields/methods, replace subschema with `"$ref"` to external/separate schema.
-12. From `@Schema(allOf = …)` on fields/methods, include `"allOf"` parts.
-13. From `@Schema(anyOf = …)` on fields/methods, include `"anyOf"` parts.
-14. From `@Schema(oneOf = …)` on fields/methods, include `"oneOf"` parts.
-15. From `@Schema(not = …)` on fields/methods, include the indicated `"not"` subschema.
-16. From `@Schema(required = true)` on fields/methods, mark property as `"required"` in the schema containing the property.
-17. From `@Schema(requiredProperties = …)` on fields/methods, derive its `"required"` properties.
-18. From `@Schema(minProperties = …)` on fields/methods, derive its `"minProperties"`.
-19. From `@Schema(maxProperties = …)` on fields/methods, derive its `"maxProperties"`.
-20. From `@Schema(nullable = true)` on fields/methods, include `null` in its `"type"`.
-21. From `@Schema(allowableValues = …)` on fields/methods, derive its `"const"`/`"enum"`.
-22. From `@Schema(defaultValue = …)` on fields/methods, derive its `"default"`.
-23. From `@Schema(accessMode = AccessMode.READ_ONLY)` on fields/methods, to mark them as `"readOnly"`.
-24. From `@Schema(accessMode = AccessMode.WRITE_ONLY)` on fields/methods, to mark them as `"writeOnly"`.
-25. From `@Schema(minLength = …)` on fields/methods, derive its `"minLength"`.
-26. From `@Schema(maxLength = …)` on fields/methods, derive its `"maxLength"`.
-27. From `@Schema(format = …)` on fields/methods, derive its `"format"`.
-28. From `@Schema(pattern = …)` on fields/methods, derive its `"pattern"`.
-29. From `@Schema(multipleOf = …)` on fields/methods, derive its `"multipleOf"`.
-30. From `@Schema(minimum = …, exclusiveMinimum = …)` on fields/methods, derive its `"minimum"`/`"exclusiveMinimum"`.
-31. From `@Schema(maximum = …, exclusiveMaximum = …)` on fields/methods, derive its `"maximum"`/`"exclusiveMaximum"`.
-32. From `@ArraySchema(minItems = …)` on fields/methods, derive its `"minItems"`.
-33. From `@ArraySchema(maxItems = …)` on fields/methods, derive its `"maxItems"`.
-34. From `@ArraySchema(uniqueItems = …)` on fields/methods, derive its `"uniqueItems"`.
+ 3. From `@Schema(ref = …)` on types in general, replace subschema with `"$ref"` to external/separate schema (except for the main type being targeted).
+ 4. From `@Schema(subTypes = …)` on types in general, derive `"anyOf"` alternatives.
+ 5. From `@Schema(anyOf = …)` on types in general (as alternative to `subTypes`), derive `"anyOf"` alternatives.
+ 6. From `@Schema(name = …)` on types in general, derive the keys/names in `"definitions"`/`"$defs"`.
+ 7. From `@Schema(description = …)` on fields/methods, derive `"description"`.
+ 8. From `@Schema(title = …)` on fields/methods, derive `"title"`.
+ 9. From `@Schema(implementation = …)` on fields/methods, override represented type.
+10. From `@Schema(hidden = true)` on fields/methods, skip certain properties.
+11. From `@Schema(name = …)` on fields/methods, override property names.
+12. From `@Schema(ref = …)` on fields/methods, replace subschema with `"$ref"` to external/separate schema.
+13. From `@Schema(allOf = …)` on fields/methods, include `"allOf"` parts.
+14. From `@Schema(anyOf = …)` on fields/methods, include `"anyOf"` parts.
+15. From `@Schema(oneOf = …)` on fields/methods, include `"oneOf"` parts.
+16. From `@Schema(not = …)` on fields/methods, include the indicated `"not"` subschema.
+17. From `@Schema(requiredMode = REQUIRED)` or `@Schema(required = true)` on fields/methods, mark property as `"required"` in the schema containing the property.
+18. From `@Schema(requiredProperties = …)` on fields/methods, derive its `"required"` properties.
+19. From `@Schema(minProperties = …)` on fields/methods, derive its `"minProperties"`.
+20. From `@Schema(maxProperties = …)` on fields/methods, derive its `"maxProperties"`.
+21. From `@Schema(nullable = true)` on fields/methods, include `null` in its `"type"`.
+22. From `@Schema(allowableValues = …)` on fields/methods, derive its `"const"`/`"enum"`.
+23. From `@Schema(defaultValue = …)` on fields/methods, derive its `"default"`.
+24. From `@Schema(accessMode = AccessMode.READ_ONLY)` on fields/methods, to mark them as `"readOnly"`.
+25. From `@Schema(accessMode = AccessMode.WRITE_ONLY)` on fields/methods, to mark them as `"writeOnly"`.
+26. From `@Schema(minLength = …)` on fields/methods, derive its `"minLength"`.
+27. From `@Schema(maxLength = …)` on fields/methods, derive its `"maxLength"`.
+28. From `@Schema(format = …)` on fields/methods, derive its `"format"`.
+29. From `@Schema(pattern = …)` on fields/methods, derive its `"pattern"`.
+30. From `@Schema(multipleOf = …)` on fields/methods, derive its `"multipleOf"`.
+31. From `@Schema(minimum = …, exclusiveMinimum = …)` on fields/methods, derive its `"minimum"`/`"exclusiveMinimum"`.
+32. From `@Schema(maximum = …, exclusiveMaximum = …)` on fields/methods, derive its `"maximum"`/`"exclusiveMaximum"`.
+33. From `@ArraySchema(minItems = …)` on fields/methods, derive its `"minItems"`.
+34. From `@ArraySchema(maxItems = …)` on fields/methods, derive its `"maxItems"`.
+35. From `@ArraySchema(uniqueItems = …)` on fields/methods, derive its `"uniqueItems"`.
 
 Schema attributes derived from `@Schema` on fields are also applied to their respective getter methods.
 Schema attributes derived from `@Schema` on getter methods are also applied to their associated fields.

jsonschema-module-swagger-2/src/main/java/com/github/victools/jsonschema/module/swagger2/Swagger2Module.java

@@ -167,7 +167,9 @@ protected String resolveTitle(MemberScope<?, ?> member) {
      * @return whether the field/method is required
      */
     protected boolean checkRequired(MemberScope<?, ?> member) {
-        return this.getSchemaAnnotationValue(member, Schema::required, Boolean.TRUE::equals)
+        return this.getSchemaAnnotationValue(member,
+                        schemaAnnotation -> schemaAnnotation.requiredMode() == Schema.RequiredMode.REQUIRED || schemaAnnotation.required(),
+                        Boolean.TRUE::equals)
                 .isPresent();
     }
 

jsonschema-module-swagger-2/src/test/java/com/github/victools/jsonschema/module/swagger2/IntegrationTest.java

@@ -97,10 +97,11 @@ static class TestClass {
         @Schema(description = "field description", nullable = true, allowableValues = {"A", "B", "C", "D"}, minLength = 1, maxLength = 1)
         public String fieldWithDescriptionAndAllowableValues;
 
-        @Schema(minimum = "15", maximum = "20", multipleOf = 0.0123456789)
+        @Schema(minimum = "15", maximum = "20", multipleOf = 0.0123456789, requiredMode = Schema.RequiredMode.NOT_REQUIRED)
         public BigDecimal fieldWithInclusiveNumericRange;
 
-        @Schema(minimum = "14", maximum = "21", exclusiveMinimum = true, exclusiveMaximum = true, required = true, multipleOf = 0.1)
+        @Schema(minimum = "14", maximum = "21", exclusiveMinimum = true, exclusiveMaximum = true, multipleOf = 0.1,
+                requiredMode = Schema.RequiredMode.REQUIRED)
         public int fieldWithExclusiveNumericRange;
     }
 

slate-docs/source/includes/_swagger-2-module.md

@@ -28,7 +28,7 @@ SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(Sc
 14. From `@Schema(anyOf = …)` on fields/methods, include `"anyOf"` parts.
 15. From `@Schema(oneOf = …)` on fields/methods, include `"oneOf"` parts.
 16. From `@Schema(not = …)` on fields/methods, include the indicated `"not"` subschema.
-17. From `@Schema(required = true)` on fields/methods, mark property as `"required"` in the schema containing the property.
+17. From `@Schema(requiredMode = REQUIRED)` or `@Schema(required = true)` on fields/methods, mark property as `"required"` in the schema containing the property.
 18. From `@Schema(requiredProperties = …)` on fields/methods, derive its `"required"` properties.
 19. From `@Schema(minProperties = …)` on fields/methods, derive its `"minProperties"`.
 20. From `@Schema(maxProperties = …)` on fields/methods, derive its `"maxProperties"`.