Merge pull request #2882 from swagger-api/bugfix/issue-2839-ref-support

ref #2389 Ref Support in Parameters and RequestBody in master.
swagger-api · Aug 6, 2018 · 2f3e488 · 2f3e488
2 parents 110ae2b + 865cb98
commit 2f3e488
Show file tree

Hide file tree

Showing 36 changed files with 1,113 additions and 56 deletions.
diff --git a/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/Parameter.java b/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/Parameter.java
@@ -167,4 +167,12 @@
      * @return an optional array of extensions
      */
     Extension[] extensions() default {};
+
+    /**
+     * A reference to a parameter defined in components parameter.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
 }
diff --git a/...s/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/callbacks/Callback.java b/...s/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/callbacks/Callback.java
@@ -69,4 +69,11 @@
      */
     Extension[] extensions() default {};
 
+    /**
+     * A reference to a Callback defined in components Callbacks.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
 }
diff --git a/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/headers/Header.java b/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/headers/Header.java
@@ -72,4 +72,12 @@
      **/
     boolean deprecated() default false;
 
+    /**
+     * A reference to a header defined in components headers.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
+
 }
diff --git a/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/links/Link.java b/modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/links/Link.java
@@ -91,4 +91,12 @@
      */
     Extension[] extensions() default {};
 
+    /**
+     * A reference to a link defined in components links.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
+
 }
diff --git a/.../swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/ExampleObject.java b/.../swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/media/ExampleObject.java
@@ -69,4 +69,12 @@
      */
     Extension[] extensions() default {};
 
+    /**
+     * A reference to a example defined in components examples.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
+
 }
diff --git a/...agger-annotations/src/main/java/io/swagger/v3/oas/annotations/parameters/RequestBody.java b/...agger-annotations/src/main/java/io/swagger/v3/oas/annotations/parameters/RequestBody.java
@@ -67,5 +67,13 @@
      * @return an optional array of extensions
      */
     Extension[] extensions() default {};
+
+    /**
+     * A reference to a RequestBody defined in components RequestBodies.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
 
 }
diff --git a/...gger-annotations/src/main/java/io/swagger/v3/oas/annotations/security/SecurityScheme.java b/...gger-annotations/src/main/java/io/swagger/v3/oas/annotations/security/SecurityScheme.java
@@ -113,4 +113,12 @@
      */
     Extension[] extensions() default {};
 
+    /**
+     * A reference to a SecurityScheme defined in components securitySchemes.
+     *
+     * @since 2.0.3
+     * @return the reference
+     **/
+    String ref() default "";
+
 }
diff --git a/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/CallbackSerializer.java b/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/CallbackSerializer.java
@@ -0,0 +1,31 @@
+package io.swagger.v3.core.jackson;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonSerializer;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import io.swagger.v3.oas.models.callbacks.Callback;
+import org.apache.commons.lang3.StringUtils;
+
+import java.io.IOException;
+
+public class CallbackSerializer extends JsonSerializer<Callback> {
+
+    public CallbackSerializer() {
+    }
+
+    @Override
+    public void serialize(
+            Callback value, JsonGenerator jgen, SerializerProvider provider)
+            throws IOException, JsonProcessingException {
+
+        // handle ref schema serialization skipping all other props
+        if (StringUtils.isBlank(value.get$ref())) {
+            provider.defaultSerializeValue(value, jgen);
+        } else {
+            jgen.writeStartObject();
+            jgen.writeStringField("$ref", value.get$ref());
+            jgen.writeEndObject();
+        }
+    }
+}
diff --git a/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/mixin/OperationMixin.java b/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/mixin/OperationMixin.java
@@ -0,0 +1,21 @@
+package io.swagger.v3.core.jackson.mixin;
+
+import com.fasterxml.jackson.annotation.JsonAnyGetter;
+import com.fasterxml.jackson.annotation.JsonAnySetter;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import io.swagger.v3.core.jackson.CallbackSerializer;
+import io.swagger.v3.oas.models.callbacks.Callback;
+
+import java.util.Map;
+
+public abstract class OperationMixin {
+
+    @JsonAnyGetter
+    public abstract Map<String, Object> getExtensions();
+
+    @JsonAnySetter
+    public abstract void addExtension(String name, Object value);
+
+    @JsonSerialize(contentUsing = CallbackSerializer.class)
+    public abstract Map<String, Callback> getCallbacks();
+}
diff --git a/modules/swagger-core/src/main/java/io/swagger/v3/core/util/AnnotationsUtils.java b/modules/swagger-core/src/main/java/io/swagger/v3/core/util/AnnotationsUtils.java
@@ -321,6 +321,9 @@ public static Optional<Example> getExample(ExampleObject example) {
                     exampleObject.setValue(example.value());
                 }
             }
+            if (StringUtils.isNotBlank(example.ref())) {
+                exampleObject.set$ref(example.ref());
+            }
             if (example.extensions().length > 0) {
                 Map<String, Object> extensions = AnnotationsUtils.getExtensions(example.extensions());
                 if (extensions != null) {
@@ -815,6 +818,10 @@ public static Optional<Link> getLink(io.swagger.v3.oas.annotations.links.Link li
                 isEmpty = false;
             }
         }
+        if (StringUtils.isNotBlank(link.ref())) {
+            linkObject.set$ref(link.ref());
+            isEmpty = false;
+        }
         if (link.extensions() != null && link.extensions().length > 0) {
             Map<String, Object> extensions = AnnotationsUtils.getExtensions(link.extensions());
             if (extensions != null) {
@@ -891,6 +898,10 @@ public static Optional<Header> getHeader(io.swagger.v3.oas.annotations.headers.H
             headerObject.setDescription(header.description());
             isEmpty = false;
         }
+        if (StringUtils.isNotBlank(header.ref())) {
+            headerObject.set$ref(header.ref());
+            isEmpty = false;
+        }
         if (header.deprecated()) {
             headerObject.setDeprecated(header.deprecated());
         }

diff --git a/modules/swagger-core/src/main/java/io/swagger/v3/core/util/ObjectMapperFactory.java b/modules/swagger-core/src/main/java/io/swagger/v3/core/util/ObjectMapperFactory.java
@@ -15,6 +15,7 @@
 import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
 import io.swagger.v3.core.jackson.SchemaSerializer;
 import io.swagger.v3.core.jackson.mixin.ExtensionsMixin;
+import io.swagger.v3.core.jackson.mixin.OperationMixin;
 import io.swagger.v3.oas.models.Components;
 import io.swagger.v3.oas.models.ExternalDocumentation;
 import io.swagger.v3.oas.models.OpenAPI;
@@ -46,10 +47,8 @@
 import io.swagger.v3.oas.models.servers.ServerVariables;
 import io.swagger.v3.oas.models.tags.Tag;
 
-import java.util.Arrays;
-import java.util.List;
-import java.util.function.Function;
-import java.util.stream.Collectors;
+import java.util.LinkedHashMap;
+import java.util.Map;
 
 public class ObjectMapperFactory {
 
@@ -91,40 +90,40 @@ public JsonSerializer<?> modifySerializer(
         Module deserializerModule = new DeserializationModule();
         mapper.registerModule(deserializerModule);
 
-        List<Class<?>> mixinTargets = Arrays.asList(
-                ApiResponse.class,
-                Callback.class,
-                Components.class,
-                Contact.class,
-                Encoding.class,
-                EncodingProperty.class,
-                Example.class,
-                ExternalDocumentation.class,
-                Header.class,
-                Info.class,
-                License.class,
-                Link.class,
-                LinkParameter.class,
-                MediaType.class,
-                OAuthFlow.class,
-                OAuthFlows.class,
-                OpenAPI.class,
-                Operation.class,
-                Parameter.class,
-                PathItem.class,
-                Paths.class,
-                RequestBody.class,
-                Scopes.class,
-                SecurityScheme.class,
-                Server.class,
-                ServerVariable.class,
-                ServerVariables.class,
-                Tag.class,
-                XML.class,
-                Schema.class
-        );
-        mapper.setMixIns(mixinTargets.stream().collect(Collectors.toMap(Function.identity(), c -> ExtensionsMixin.class)));
+        Map<Class<?>, Class<?>> sourceMixins = new LinkedHashMap<>();
 
+        sourceMixins.put(ApiResponse.class, ExtensionsMixin.class);
+        sourceMixins.put(Callback.class, ExtensionsMixin.class);
+        sourceMixins.put(Components.class, ExtensionsMixin.class);
+        sourceMixins.put(Contact.class, ExtensionsMixin.class);
+        sourceMixins.put(Encoding.class, ExtensionsMixin.class);
+        sourceMixins.put(EncodingProperty.class, ExtensionsMixin.class);
+        sourceMixins.put(Example.class, ExtensionsMixin.class);
+        sourceMixins.put(ExternalDocumentation.class, ExtensionsMixin.class);
+        sourceMixins.put(Header.class, ExtensionsMixin.class);
+        sourceMixins.put(Info.class, ExtensionsMixin.class);
+        sourceMixins.put(License.class, ExtensionsMixin.class);
+        sourceMixins.put(Link.class, ExtensionsMixin.class);
+        sourceMixins.put(LinkParameter.class, ExtensionsMixin.class);
+        sourceMixins.put(MediaType.class, ExtensionsMixin.class);
+        sourceMixins.put(OAuthFlow.class, ExtensionsMixin.class);
+        sourceMixins.put(OAuthFlows.class, ExtensionsMixin.class);
+        sourceMixins.put(OpenAPI.class, ExtensionsMixin.class);
+        sourceMixins.put(Operation.class, OperationMixin.class);
+        sourceMixins.put(Parameter.class, ExtensionsMixin.class);
+        sourceMixins.put(PathItem.class, ExtensionsMixin.class);
+        sourceMixins.put(Paths.class, ExtensionsMixin.class);
+        sourceMixins.put(RequestBody.class, ExtensionsMixin.class);
+        sourceMixins.put(Scopes.class, ExtensionsMixin.class);
+        sourceMixins.put(SecurityScheme.class, ExtensionsMixin.class);
+        sourceMixins.put(Server.class, ExtensionsMixin.class);
+        sourceMixins.put(ServerVariable.class, ExtensionsMixin.class);
+        sourceMixins.put(ServerVariables.class, ExtensionsMixin.class);
+        sourceMixins.put(Tag.class, ExtensionsMixin.class);
+        sourceMixins.put(XML.class, ExtensionsMixin.class);
+        sourceMixins.put(Schema.class, ExtensionsMixin.class);
+
+        mapper.setMixIns(sourceMixins);
         mapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);
         mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
         mapper.configure(SerializationFeature.WRITE_ENUMS_USING_TO_STRING, true);

diff --git a/modules/swagger-core/src/main/java/io/swagger/v3/core/util/ParameterProcessor.java b/modules/swagger-core/src/main/java/io/swagger/v3/core/util/ParameterProcessor.java
@@ -72,6 +72,11 @@ public static Parameter applyAnnotations(
                 if (p.hidden()) {
                     return null;
                 }
+                if (StringUtils.isNotBlank(p.ref())) {
+                    parameter = new Parameter().$ref(p.ref());
+                    return parameter;
+                }
+
                 if (StringUtils.isNotBlank(p.description())) {
                     parameter.setDescription(p.description());
                 }

diff --git a/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/DefaultParameterExtension.java b/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/DefaultParameterExtension.java
@@ -126,15 +126,16 @@ public ResolvedParameter extractParameters(List<Annotation> annotations,
             }
         }
         for (Parameter p : parameters) {
-            if (ParameterProcessor.applyAnnotations(
+            Parameter processedParameter = ParameterProcessor.applyAnnotations(
                     p,
                     type,
                     annotations,
                     components,
                     classConsumes == null ? new String[0] : classConsumes.value(),
                     methodConsumes == null ? new String[0] : methodConsumes.value(),
-                    jsonViewAnnotation) != null) {
-                extractParametersResult.parameters.add(p);
+                    jsonViewAnnotation);
+            if (processedParameter != null) {
+                extractParametersResult.parameters.add(processedParameter);
             }
         }
         return extractParametersResult;
@@ -224,15 +225,16 @@ private boolean handleAdditionalAnnotation(List<Parameter> parameters, Annotatio
                                 extensions).parameters;
 
                 for (Parameter p : extracted) {
-                    if (ParameterProcessor.applyAnnotations(
+                    Parameter processedParam = ParameterProcessor.applyAnnotations(
                             p,
                             paramType,
                             paramAnnotations,
                             components,
                             classConsumes == null ? new String[0] : classConsumes.value(),
                             methodConsumes == null ? new String[0] : methodConsumes.value(),
-                            jsonViewAnnotation) != null) {
-                        parameters.add(p);
+                            jsonViewAnnotation);
+                    if (processedParam != null) {
+                        parameters.add(processedParam);
                     }
                 }
 

diff --git a/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/OperationParser.java b/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/OperationParser.java
@@ -24,6 +24,12 @@ public static Optional<RequestBody> getRequestBody(io.swagger.v3.oas.annotations
         }
         RequestBody requestBodyObject = new RequestBody();
         boolean isEmpty = true;
+
+        if (StringUtils.isNotBlank(requestBody.ref())) {
+            requestBodyObject.set$ref(requestBody.ref());
+            return Optional.of(requestBodyObject);
+        }
+
         if (StringUtils.isNotBlank(requestBody.description())) {
             requestBodyObject.setDescription(requestBody.description());
             isEmpty = false;

diff --git a/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/Reader.java b/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/Reader.java
@@ -1014,7 +1014,13 @@ private Map<String, Callback> getCallbacks(
         if (apiCallback == null) {
             return callbackMap;
         }
+
         Callback callbackObject = new Callback();
+        if (StringUtils.isNotBlank(apiCallback.ref())) {
+            callbackObject.set$ref(apiCallback.ref());
+            callbackMap.put(apiCallback.name(), callbackObject);
+            return callbackMap;
+        }
         PathItem pathItemObject = new PathItem();
         for (io.swagger.v3.oas.annotations.Operation callbackOperation : apiCallback.operation()) {
             Operation callbackNewOperation = new Operation();

diff --git a/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/SecurityParser.java b/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/SecurityParser.java
@@ -75,7 +75,9 @@ public static Optional<SecuritySchemePair> getSecurityScheme(io.swagger.v3.oas.a
         if (StringUtils.isNotBlank(securityScheme.paramName())) {
             securitySchemeObject.setName(securityScheme.paramName());
         }
-
+        if (StringUtils.isNotBlank(securityScheme.ref())) {
+            securitySchemeObject.set$ref(securityScheme.ref());
+        }
         if (StringUtils.isNotBlank(securityScheme.name())) {
             key = securityScheme.name();
         }

diff --git a/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/util/ReaderUtils.java b/modules/swagger-jaxrs2/src/main/java/io/swagger/v3/jaxrs2/util/ReaderUtils.java
@@ -71,15 +71,16 @@ public static List<Parameter> collectConstructorParameters(Class<?> cls, Compone
                     final List<Parameter> tmpParameters = collectParameters(genericParameterType, tmpAnnotations, components, classConsumes, jsonViewAnnotation);
                     if (tmpParameters.size() >= 1) {
                         for (Parameter tmpParameter : tmpParameters) {
-                            if (ParameterProcessor.applyAnnotations(
+                            Parameter processedParameter = ParameterProcessor.applyAnnotations(
                                     tmpParameter,
                                     genericParameterType,
                                     tmpAnnotations,
                                     components,
                                     classConsumes == null ? new String[0] : classConsumes.value(),
                                     null,
-                                    jsonViewAnnotation) != null) {
-                                parameters.add(tmpParameter);
+                                    jsonViewAnnotation);
+                            if (processedParameter != null) {
+                                parameters.add(processedParameter);
                             }
                         }
                         paramsCount++;