refs #2319 - response example support: tests and fixes

Author: frantuma

modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiResponse.java

@@ -86,5 +86,12 @@
      */
     String responseContainer() default "";
 
+    /**
+     * Examples for the response.
+     *
+     * @since 1.5.20
+     *
+     * @return
+     */
     Example examples() default @Example(value = @ExampleProperty(value = "", mediaType = ""));
 }

modules/swagger-jaxrs/src/main/java/io/swagger/jaxrs/Reader.java

@@ -23,7 +23,23 @@
 import com.fasterxml.jackson.databind.introspect.AnnotatedMethod;
 import com.fasterxml.jackson.databind.introspect.AnnotatedParameter;
 import com.fasterxml.jackson.databind.type.TypeFactory;
-import io.swagger.annotations.*;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiKeyAuthDefinition;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+import io.swagger.annotations.AuthorizationScope;
+import io.swagger.annotations.BasicAuthDefinition;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
+import io.swagger.annotations.Info;
+import io.swagger.annotations.OAuth2Definition;
+import io.swagger.annotations.ResponseHeader;
+import io.swagger.annotations.Scope;
+import io.swagger.annotations.SwaggerDefinition;
 import io.swagger.converter.ModelConverters;
 import io.swagger.jaxrs.config.DefaultReaderConfig;
 import io.swagger.jaxrs.config.ReaderConfig;
@@ -996,7 +1012,9 @@ private void addResponse(Operation operation, ApiResponse apiResponse, JsonView
         Map<String, Object> examples = parseExamples(apiResponse.examples());
 
         Response response = new Response()
-        .description(apiResponse.message()).headers(responseHeaders).setExamples(examples);
+                .description(apiResponse.message())
+                .headers(responseHeaders);
+        response.setExamples(examples);
 
         if (apiResponse.code() == 0) {
             operation.defaultResponse(response);
@@ -1028,7 +1046,7 @@ private Map<String, Object> parseExamples(Example examples) {
                 continue;
             }
 
-            map = map == null ? new HashMap<String, Object>() : map;
+            map = map == null ? new LinkedHashMap<String, Object>() : map;
             map.put(prop.mediaType(), prop.value());
         }
         return map;

modules/swagger-jaxrs/src/test/java/io/swagger/SimpleReaderTest.java

@@ -50,6 +50,7 @@
 import io.swagger.resources.ResourceWithMapReturnValue;
 import io.swagger.resources.ResourceWithRanges;
 import io.swagger.resources.ResourceWithResponse;
+import io.swagger.resources.ResourceWithResponseExamples;
 import io.swagger.resources.ResourceWithResponseHeaders;
 import io.swagger.resources.ResourceWithTypedResponses;
 import io.swagger.resources.ResourceWithVoidReturns;
@@ -585,6 +586,30 @@ public void checkResponseModelsProcessing() {
         }
     }
 
+    @Test(description = "test response examples")
+    public void testResponseExamples() {
+        Swagger swagger = getSwagger(ResourceWithResponseExamples.class);
+        for (Map.Entry<String, Path> entry : swagger.getPaths().entrySet()) {
+            String name = entry.getKey().substring(entry.getKey().lastIndexOf("/") + 1);
+            if ("testPrimitiveResponses".equals(name)) {
+                Map<String, String[]> expected = ImmutableMap.of("404", new String[]{"string", null});
+                assertEquals(entry.getValue().getGet().getResponses().size(), expected.size());
+                for (Map.Entry<String, Response> responseEntry : entry.getValue().getGet().getResponses().entrySet()) {
+                    String[] expectedProp = expected.get(responseEntry.getKey());
+                    Model model = responseEntry.getValue().getResponseSchema();
+                    ModelImpl modelImpl = (ModelImpl) model;
+                    assertEquals(modelImpl.getType(), expectedProp[0]);
+                    assertEquals(modelImpl.getFormat(), expectedProp[1]);
+                    Response response = responseEntry.getValue();
+                    assertEquals(response.getExamples().size(), 2);
+                    assertEquals(response.getExamples().get("*/*").toString(), "message example 1");
+                    assertEquals(response.getExamples().get("application/json").toString(), "message example 2");
+                }
+            }
+        }
+    }
+
+
     @Test(description = "scan a resource with custom operation nickname")
     public void scanResourceWithApiOperationNickname() {
         Swagger swagger = getSwagger(NicknamedOperation.class);

modules/swagger-jaxrs/src/test/java/io/swagger/resources/ResourceWithResponseExamples.java

@@ -0,0 +1,35 @@
+package io.swagger.resources;
+
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.core.Response;
+
+@Api(value = "/root")
+@Path("/")
+public class ResourceWithResponseExamples {
+
+    @GET
+    @Path("testPrimitiveResponses")
+    @ApiResponses({
+            @ApiResponse(
+                    code = 404,
+                    message = "Message for String",
+                    response = String.class,
+                    examples = @Example(value =
+                            {
+                                    @ExampleProperty(mediaType = "*/*", value = "message example 1"),
+                                    @ExampleProperty(mediaType = "application/json", value = "message example 2")
+                            }
+                    ))
+    })
+    public Response testPrimitiveResponses() {
+        return null;
+    }
+
+}

modules/swagger-models/src/main/java/io/swagger/models/Response.java

@@ -91,9 +91,8 @@ public Map<String, Object> getExamples() {
         return this.examples;
     }
 
-    public Response setExamples(Map<String, Object> examples) {
+    public void setExamples(Map<String, Object> examples) {
         this.examples = examples;
-        return this;
     }
 
     public Map<String, Property> getHeaders() {