OAS 3.1 Initial support - Schema properties support in annotations - Enhanced Response Schema resolving

.mvn/wrapper/MavenWrapperDownloader.java

@@ -20,7 +20,7 @@
 
 public class MavenWrapperDownloader {
 
-    private static final String WRAPPER_VERSION = "0.5.3";
+    private static final String WRAPPER_VERSION = "0.5.6";
     /**
      * Default URL to download the maven-wrapper.jar from, if no 'downloadUrl' is provided.
      */

.mvn/wrapper/maven-wrapper.properties

@@ -1,2 +1,2 @@
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.6.3/apache-maven-3.6.3-bin.zip
-wrapperUrl=https://repo.maven.apache.org/maven2/io/takari/maven-wrapper/0.5.3/maven-wrapper-0.5.3.jar
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.4/apache-maven-3.8.4-bin.zip
+wrapperUrl=https://repo.maven.apache.org/maven2/io/takari/maven-wrapper/0.5.3/maven-wrapper-0.5.6.jar

README.md

@@ -80,7 +80,7 @@ You need the following installed and available in your $PATH:
 * Jackson 2.4.5 or greater
 
 
-### To build from source (currently 2.1.14-SNAPSHOT)
+### To build from source (currently 2.2.0-SNAPSHOT)
 ```
 # first time building locally
 mvn -N

modules/swagger-annotations/pom.xml

@@ -3,7 +3,7 @@
     <parent>
         <groupId>io.swagger.core.v3</groupId>
         <artifactId>swagger-project</artifactId>
-        <version>2.1.14-SNAPSHOT</version>
+        <version>2.2.0-SNAPSHOT</version>
         <relativePath>../..</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/Content.java

@@ -62,6 +62,22 @@
      **/
     Schema schema() default @Schema();
 
+    /**
+     * The schema properties defined for schema provided in @Schema
+     *
+     * @since 2.2.0
+     * @return the schema properties
+     */
+    SchemaProperty[] schemaProperties() default {};
+
+    /**
+     * The schema properties defined for schema provided in @Schema
+     *
+     * @since 2.2.0
+     * @return the schema properties
+     */
+    Schema additionalPropertiesSchema() default @Schema();
+
     /**
      * The schema of the array that defines the type used for the content.
      *

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/PatternProperties.java

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2017 SmartBear Software
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.swagger.v3.oas.annotations.media;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * Container for repeatable {@link PatternProperty} annotation
+ *
+ * @see PatternProperty
+ */
+@Target({FIELD, METHOD, PARAMETER, TYPE, ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+public @interface PatternProperties {
+    /**
+     * An array of PatternProperty annotations
+     *
+     * @return the array of the PatternProperty
+     **/
+    PatternProperty[] value() default {};
+
+}

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/PatternProperty.java

@@ -0,0 +1,65 @@
+/**
+ * Copyright 2021 SmartBear Software
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.swagger.v3.oas.annotations.media;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * The annotation may be used in OpenAPI 3.1 schemas / JSON Schema.
+ *
+ * @see <a target="_new" href="https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-10.3.2.2">JSON Schema section 10.3.2.2</a>
+ * @see Schema
+ *
+ * @since 2.1.8
+ **/
+@Target({FIELD, METHOD, PARAMETER, TYPE, ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+@Repeatable(PatternProperties.class)
+public @interface PatternProperty {
+    /**
+     * The regex.
+     *
+     * @return the regex
+     **/
+    String regex() default "";
+
+    /**
+     * The schema to validate against for properties matching the regex.
+     *
+     * @return the schema
+     **/
+    Schema schema() default @Schema();
+
+    /**
+     * The schema of the array to validate against for properties matching the regex.
+     *
+     * @return the schema of the array
+     */
+    ArraySchema array() default @ArraySchema();
+
+}

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/Schema.java

@@ -23,7 +23,6 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import java.nio.file.AccessMode;
 
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.TYPE;
@@ -329,10 +328,29 @@
      */
     Extension[] extensions() default {};
 
+    /**
+     * Allows to specify the additionalProperties value
+     *
+     * AdditionalPropertiesValue.TRUE: set to TRUE
+     * AdditionalPropertiesValue.FALSE: set to FALSE
+     * AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION: resolve from @Content.additionalPropertiesSchema
+     *
+     * @since 2.2.0
+     * @return the accessMode for this schema (property)
+     *
+     */
+    AdditionalPropertiesValue additionalProperties() default AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION;
+
     enum AccessMode {
         AUTO,
         READ_ONLY,
         WRITE_ONLY,
         READ_WRITE;
     }
+
+    enum AdditionalPropertiesValue {
+        TRUE,
+        FALSE,
+        USE_ADDITIONAL_PROPERTIES_ANNOTATION;
+    }
 }

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/SchemaProperties.java

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2017 SmartBear Software
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.swagger.v3.oas.annotations.media;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * Container for repeatable {@link SchemaProperty} annotation
+ *
+ * @see SchemaProperty
+ */
+@Target({FIELD, METHOD, PARAMETER, TYPE, ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+public @interface SchemaProperties {
+    /**
+     * An array of SchemaProperty annotations
+     *
+     * @return the array of the SchemaProperty
+     **/
+    SchemaProperty[] value() default {};
+
+}

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/SchemaProperty.java

@@ -0,0 +1,64 @@
+/**
+ * Copyright 2021 SmartBear Software
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.swagger.v3.oas.annotations.media;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * The annotation may be used to define properties for an Object Schema
+ *
+ * @see Schema
+ *
+ * @since 2.1.8
+ **/
+@Target({FIELD, METHOD, PARAMETER, TYPE, ANNOTATION_TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+@Repeatable(SchemaProperties.class)
+public @interface SchemaProperty {
+    /**
+     * The name.
+     *
+     * @return the name
+     **/
+    String name() default "";
+
+    /**
+     * The schema of the property.
+     *
+     * @return the schema
+     **/
+    Schema schema() default @Schema();
+
+    /**
+     * The schema of the array.
+     *
+     * @return the schema of the array
+     */
+    ArraySchema array() default @ArraySchema();
+
+}

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/responses/ApiResponse.java

@@ -96,4 +96,11 @@
      **/
     String ref() default "";
 
+    /**
+     * Set to true to resolve the response schema from method return type
+     *
+     * @since 2.2.0
+     **/
+    boolean useReturnTypeSchema() default false;
+
 }

modules/swagger-core/pom.xml

@@ -3,7 +3,7 @@
     <parent>
         <groupId>io.swagger.core.v3</groupId>
         <artifactId>swagger-project</artifactId>
-        <version>2.1.14-SNAPSHOT</version>
+        <version>2.2.0-SNAPSHOT</version>
         <relativePath>../..</relativePath>
     </parent>
     <modelVersion>4.0.0</modelVersion>

modules/swagger-core/src/main/java/io/swagger/v3/core/converter/ModelConverters.java

@@ -97,14 +97,7 @@ public ResolvedSchema readAllAsResolvedSchema(Type type) {
     }
     public ResolvedSchema readAllAsResolvedSchema(AnnotatedType type) {
         if (shouldProcess(type.getType())) {
-            ModelConverterContextImpl context = new ModelConverterContextImpl(
-                    converters);
-
-            ResolvedSchema resolvedSchema = new ResolvedSchema();
-            resolvedSchema.schema = context.resolve(type);
-            resolvedSchema.referencedSchemas = context.getDefinedModels();
-
-            return resolvedSchema;
+            return resolveAsResolvedSchema(type);
         }
         return null;
     }

modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/CallbackSerializer.java

@@ -18,16 +18,19 @@ public void serialize(
             Callback value, JsonGenerator jgen, SerializerProvider provider)
             throws IOException {
 
+        // has extensions
         if (value != null && value.getExtensions() != null && !value.getExtensions().isEmpty()) {
             jgen.writeStartObject();
 
+            // not a ref
             if (StringUtils.isBlank(value.get$ref())) {
                 if (!value.isEmpty()) {
+                    // write map
                     for (Entry<String, PathItem> entry: value.entrySet()) {
                         jgen.writeObjectField(entry.getKey() , entry.getValue());
                     }
                 }
-            } else { // handle ref schema serialization skipping all other props
+            } else { // handle ref schema serialization skipping all other props ...
                 jgen.writeStringField("$ref", value.get$ref());
             }
             for (String ext: value.getExtensions().keySet()) {