Allow ApiResponse.reference to be set as Schema.$ref in json and yaml

pom.xml

@@ -93,7 +93,7 @@
         <version.maven-gpg-plugin>1.6</version.maven-gpg-plugin>
         <version.plexus-javadoc>1.0</version.plexus-javadoc>
         <version.slf4j-nop>1.7.25</version.slf4j-nop>
-        <kotlin.version>1.2.61</kotlin.version>
+        <kotlin.version>1.5.32</kotlin.version>
     </properties>
 
     <dependencies>

src/main/java/com/github/kongchen/swagger/docgen/reader/AbstractReader.java

@@ -42,7 +42,7 @@ public abstract class AbstractReader {
     protected List<ResponseMessageOverride> responseMessageOverrides;
 
     protected String operationIdFormat;
-    
+
     /**
      * Supported parameters: {{packageName}}, {{className}}, {{methodName}}, {{httpMethod}}
      * Suggested default value is: "{{className}}_{{methodName}}_{{httpMethod}}"
@@ -386,7 +386,11 @@ protected void updateApiResponse(Operation operation, ApiResponses responseAnnot
                     .description(apiResponse.message())
                     .headers(responseHeaders);
 
-            if (responseClass.equals(Void.class)) {
+            if (apiResponse.reference() != null && !"".equals(apiResponse.reference()) && responseClass.equals(Void.class) ) {
+                ModelReference model = new ModelReference();
+                model.setReference(apiResponse.reference());
+                response.setResponseSchema(model);
+            } else if (responseClass.equals(Void.class)) {
                 if (operation.getResponses() != null) {
                     Response apiOperationResponse = operation.getResponses().get(String.valueOf(apiResponse.code()));
                     if (apiOperationResponse != null) {
@@ -522,22 +526,22 @@ void processOperationDecorator(Operation operation, Method method) {
             extension.decorateOperation(operation, method, chain);
         }
     }
-    
+
     protected String getOperationId(Method method, String httpMethod) {
   		if (this.operationIdFormat == null) {
   			this.operationIdFormat = OPERATION_ID_FORMAT_DEFAULT;
   		}
-  		
+
   		String packageName = method.getDeclaringClass().getPackage().getName();
   		String className = method.getDeclaringClass().getSimpleName();
   		String methodName = method.getName();
-        
+
   		StrBuilder sb = new StrBuilder(this.operationIdFormat);
   		sb.replaceAll("{{packageName}}", packageName);
   		sb.replaceAll("{{className}}", className);
   		sb.replaceAll("{{methodName}}", methodName);
   		sb.replaceAll("{{httpMethod}}", httpMethod);
-  		
+
   		return sb.toString();
     }
 

src/main/java/com/github/kongchen/swagger/docgen/reader/ModelReference.java

@@ -0,0 +1,89 @@
+package com.github.kongchen.swagger.docgen.reader;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.models.ExternalDocs;
+import io.swagger.models.Model;
+import io.swagger.models.properties.Property;
+
+import java.util.Map;
+
+public class ModelReference implements Model {
+    @JsonIgnore
+    @Override
+    public String getTitle() {
+        return null;
+    }
+
+    @Override
+    public void setTitle(String s) {
+
+    }
+
+
+    @JsonIgnore
+    @Override
+    public String getDescription() {
+        return null;
+    }
+
+    @Override
+    public void setDescription(String s) {
+
+    }
+
+
+    @JsonIgnore
+    @Override
+    public Map<String, Property> getProperties() {
+        return null;
+    }
+
+    @Override
+    public void setProperties(Map<String, Property> map) {
+
+    }
+
+
+    @JsonIgnore
+    @Override
+    public Object getExample() {
+        return null;
+    }
+
+    @Override
+    public void setExample(Object o) {
+
+    }
+
+
+    @JsonIgnore
+    @Override
+    public ExternalDocs getExternalDocs() {
+        return null;
+    }
+
+    private String reference;
+    @JsonProperty("$ref")
+    @Override
+    public String getReference() {
+        return reference;
+    }
+
+    @Override
+    public void setReference(String s) {
+        reference = s;
+    }
+
+    @Override
+    public Object clone() {
+        return null;
+    }
+
+
+    @JsonIgnore
+    @Override
+    public Map<String, Object> getVendorExtensions() {
+        return null;
+    }
+}

src/test/java/com/wordnik/jaxrs/PetResource.java

@@ -107,7 +107,7 @@ public Response getPetsById(
     @DELETE
     @Path("/{petId}")
     @ApiOperation(value = "Deletes a pet", nickname = "removePet")
-    @ApiResponses(value = {@ApiResponse(code = 400, message = "Invalid pet value")})
+    @ApiResponses(value = {@ApiResponse(code = 400, message = "Invalid pet value", reference = "https://pet.error.com")})
     public Response deletePet(
             @ApiParam() @HeaderParam("api_key") String apiKey,
             @ApiParam(value = "Pet id to delete", required = true) @PathParam("petId") Long petId) {

src/test/resources/expectedOutput/swagger-enhanced-operation-id.json

@@ -721,7 +721,10 @@
         } ],
         "responses" : {
           "400" : {
-            "description" : "Invalid pet value"
+            "description" : "Invalid pet value",
+              "schema" : {
+                  "$ref" : "https://pet.error.com"
+              }
           }
         },
         "security" : [ {

src/test/resources/expectedOutput/swagger-externalDocs.json

@@ -993,7 +993,10 @@
         ],
         "responses": {
           "400": {
-            "description": "Invalid pet value"
+            "description": "Invalid pet value",
+              "schema" : {
+                  "$ref" : "https://pet.error.com"
+              }
           }
         },
         "security": [

src/test/resources/expectedOutput/swagger-swaggerreader.json

@@ -698,7 +698,10 @@
         } ],
         "responses" : {
           "400" : {
-            "description" : "Invalid pet value"
+            "description" : "Invalid pet value",
+              "schema" : {
+                  "$ref" : "https://pet.error.com"
+              }
           }
         },
         "security" : [ {

src/test/resources/expectedOutput/swagger-swaggerreader.yaml

@@ -623,6 +623,8 @@ paths:
       responses:
         400:
           description: "Invalid pet value"
+          schema:
+            $ref: "https://pet.error.com"
       security:
       - petstore_auth:
         - "write:pets"

src/test/resources/expectedOutput/swagger-with-converter.json

@@ -991,7 +991,10 @@
         ],
         "responses": {
           "400": {
-            "description": "Invalid pet value"
+            "description": "Invalid pet value",
+              "schema" : {
+                  "$ref" : "https://pet.error.com"
+              }
           }
         },
         "security": [

src/test/resources/expectedOutput/swagger-with-converter.yaml

@@ -698,6 +698,8 @@ paths:
       responses:
         400:
           description: "Invalid pet value"
+          schema:
+            $ref: "https://pet.error.com"
       security:
       - petstore_auth:
         - "write:pets"

src/test/resources/expectedOutput/swagger.json

@@ -993,7 +993,10 @@
         ],
         "responses": {
           "400": {
-            "description": "Invalid pet value"
+            "description": "Invalid pet value",
+              "schema" : {
+                  "$ref" : "https://pet.error.com"
+              }
           }
         },
         "security": [

src/test/resources/expectedOutput/swagger.yaml

@@ -698,6 +698,8 @@ paths:
       responses:
         400:
           description: "Invalid pet value"
+          schema:
+            $ref: "https://pet.error.com"
       security:
       - petstore_auth:
         - "write:pets"