Merge pull request #2801 from swagger-api/issue-2319-apiresponse-examples-annotation

Refs #2319 - response example support

Author: frantuma

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

@@ -85,4 +85,13 @@
      * Valid values are "List", "Set" or "Map". Any other value will be ignored.
      */
     String responseContainer() default "";
+
+    /**
+     * Examples for the response.
+     *
+     * @since 1.5.20
+     *
+     * @return
+     */
+    Example examples() default @Example(value = @ExampleProperty(value = "", mediaType = ""));
 }

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

@@ -36,7 +36,7 @@
      *
      * @return the name of the property
      */
-    String mediaType() default "default";
+    String mediaType() default "";
 
     /**
      * The value of the example.

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

@@ -33,6 +33,8 @@
 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;
@@ -1007,9 +1009,12 @@ private void processOperationDecorator(Operation operation, Method method) {
 
     private void addResponse(Operation operation, ApiResponse apiResponse, JsonView jsonView) {
         Map<String, Property> responseHeaders = parseResponseHeaders(apiResponse.responseHeaders(), jsonView);
+        Map<String, Object> examples = parseExamples(apiResponse.examples());
 
         Response response = new Response()
-        .description(apiResponse.message()).headers(responseHeaders);
+                .description(apiResponse.message())
+                .headers(responseHeaders);
+        response.setExamples(examples);
 
         if (apiResponse.code() == 0) {
             operation.defaultResponse(response);
@@ -1029,6 +1034,24 @@ private void addResponse(Operation operation, ApiResponse apiResponse, JsonView
         }
     }
 
+    private Map<String, Object> parseExamples(Example examples) {
+        if(examples == null){
+            return null;
+        }
+
+        Map<String, Object> map = null;
+        for(ExampleProperty prop : examples.value()){
+
+            if(prop.mediaType().equals("") && prop.value().equals("")){
+                continue;
+            }
+
+            map = map == null ? new LinkedHashMap<String, Object>() : map;
+            map.put(prop.mediaType(), prop.value());
+        }
+        return map;
+    }
+
     private List<Parameter> getParameters(Type type, List<Annotation> annotations) {
         final Iterator<SwaggerExtension> chain = SwaggerExtensions.chain();
         if (!chain.hasNext()) {

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;
+    }
+
+}