Feature/example values

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

@@ -109,4 +109,22 @@
      * Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}.
      */
     String paramType() default "";
+
+    /**
+     * a single example for non-body type parameters
+     *
+     * @since 1.5.4
+     *
+     * @return
+     */
+    String example() default "";
+
+    /**
+     * Examples for the parameter.  Applies only to BodyParameters
+     *
+     * @since 1.5.4
+     *
+     * @return
+     */
+    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
 }

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

@@ -92,4 +92,22 @@
      * Hides the parameter from the list of parameters.
      */
     boolean hidden() default false;
+
+    /**
+     * a single example for non-body type parameters
+     *
+     * @since 1.5.4
+     *
+     * @return
+     */
+    String example() default "";
+
+    /**
+     * Examples for the parameter.  Applies only to BodyParameters
+     *
+     * @since 1.5.4
+     *
+     * @return
+     */
+    Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));
 }

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

@@ -0,0 +1,39 @@
+/**
+ * Copyright 2015 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.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An optionally named list of example properties.
+ *
+ * @since 1.5.4
+ */
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Example {
+    /**
+     * The examples properties.
+     *
+     * @return the actual extension properties
+     * @see ExampleProperty
+     */
+    ExampleProperty[] value();
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2015 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.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A mediaType/value property within a Swagger example
+ *
+ * @see Example
+ * @since 1.5.4
+ */
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ExampleProperty {
+
+    /**
+     * The name of the property.
+     *
+     * @return the name of the property
+     */
+    String mediaType() default "default";
+
+    /**
+     * The value of the example.
+     *
+     * @return the value of the example
+     */
+    String value();
+}

modules/swagger-core/src/main/java/io/swagger/util/ParameterProcessor.java

@@ -2,6 +2,8 @@
 
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
 import io.swagger.converter.ModelConverters;
 import io.swagger.models.Model;
 import io.swagger.models.Swagger;
@@ -50,12 +52,18 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
             if (StringUtils.isNotEmpty(param.getDescription())) {
                 p.setDescription(param.getDescription());
             }
+            if (StringUtils.isNotEmpty(param.getExample())) {
+                p.setExample(param.getExample());
+            }
             if (StringUtils.isNotEmpty(param.getAccess())) {
                 p.setAccess(param.getAccess());
             }
             if (StringUtils.isNotEmpty(param.getDataType())) {
                 p.setType(param.getDataType());
             }
+            if (StringUtils.isNotEmpty(param.getExample())) {
+                p.setType(param.getExample());
+            }
             if (helper.getMinItems() != null) {
                 p.setMinItems(helper.getMinItems());
             }
@@ -80,6 +88,7 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
                     args.put(PropertyBuilder.PropertyId.MAXIMUM, p.getMaximum());
                     p.setMaximum(null);
                     args.put(PropertyBuilder.PropertyId.EXCLUSIVE_MAXIMUM, p.isExclusiveMaximum());
+                    args.put(PropertyBuilder.PropertyId.EXAMPLE, p.getExample());
                     p.setExclusiveMaximum(null);
                     Property items = PropertyBuilder.build(p.getType(), p.getFormat(), args);
                     p.type(ArrayProperty.TYPE).format(null).items(items);
@@ -103,6 +112,35 @@ public static Parameter applyAnnotations(Swagger swagger, Parameter parameter, T
             // must be a body param
             BodyParameter bp = new BodyParameter();
 
+            if (helper.getApiParam() != null) {
+                ParamWrapper<?> pw = helper.getApiParam();
+
+                if (pw instanceof ApiParamWrapper) {
+                    ApiParamWrapper apiParam = (ApiParamWrapper) pw;
+                    Example example = apiParam.getExamples();
+                    if (example != null && example.value() != null) {
+                        for (ExampleProperty ex : example.value()) {
+                            String mediaType = ex.mediaType();
+                            String value = ex.value();
+                            if (!mediaType.isEmpty() && !value.isEmpty()) {
+                                bp.example(mediaType.trim(), value.trim());
+                            }
+                        }
+                    }
+                } else if (pw instanceof ApiImplicitParamWrapper) {
+                    ApiImplicitParamWrapper apiParam = (ApiImplicitParamWrapper) pw;
+                    Example example = apiParam.getExamples();
+                    if (example != null && example.value() != null) {
+                        for (ExampleProperty ex : example.value()) {
+                            String mediaType = ex.mediaType();
+                            String value = ex.value();
+                            if (!mediaType.isEmpty() && !value.isEmpty()) {
+                                bp.example(mediaType.trim(), value.trim());
+                            }
+                        }
+                    }
+                }
+            }
             bp.setRequired(param.isRequired());
             bp.setName(StringUtils.isNotEmpty(param.getName()) ? param.getName() : "body");
 
@@ -179,6 +217,8 @@ public interface ParamWrapper<T extends Annotation> {
         T getAnnotation();
 
         boolean isHidden();
+
+        String getExample();
     }
 
     /**
@@ -341,6 +381,19 @@ public ApiParam getAnnotation() {
         public boolean isHidden() {
             return apiParam.hidden();
         }
+
+        @Override
+        public String getExample() {
+            return apiParam.example();
+        }
+
+        ;
+
+        public Example getExamples() {
+            return apiParam.examples();
+        }
+
+        ;
     }
 
     /**
@@ -408,5 +461,14 @@ public ApiImplicitParam getAnnotation() {
         public boolean isHidden() {
             return false;
         }
+
+        @Override
+        public String getExample() {
+            return apiParam.example();
+        }
+
+        public Example getExamples() {
+            return apiParam.examples();
+        }
     }
 }

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

@@ -28,32 +28,9 @@
 import io.swagger.models.properties.Property;
 import io.swagger.models.properties.RefProperty;
 import io.swagger.models.properties.StringProperty;
-import io.swagger.resources.HiddenResource;
-import io.swagger.resources.Resource1041;
-import io.swagger.resources.Resource1073;
-import io.swagger.resources.Resource1085;
-import io.swagger.resources.Resource653;
-import io.swagger.resources.Resource841;
-import io.swagger.resources.Resource877;
-import io.swagger.resources.Resource937;
-import io.swagger.resources.ResourceWithApiOperationCode;
-import io.swagger.resources.ResourceWithApiResponseResponseContainer;
-import io.swagger.resources.ResourceWithBodyParams;
-import io.swagger.resources.ResourceWithEmptyModel;
-import io.swagger.resources.ResourceWithEnums;
-import io.swagger.resources.ResourceWithInnerClass;
-import io.swagger.resources.ResourceWithMapReturnValue;
-import io.swagger.resources.ResourceWithRanges;
-import io.swagger.resources.ResourceWithResponse;
-import io.swagger.resources.ResourceWithResponseHeaders;
-import io.swagger.resources.ResourceWithTypedResponses;
-import io.swagger.resources.ResourceWithVoidReturns;
-import io.swagger.resources.SimpleResource;
-import io.swagger.resources.SimpleResourceWithoutAnnotations;
-import io.swagger.resources.SimpleSelfReferencingSubResource;
-import io.swagger.resources.TaggedResource;
-import io.swagger.resources.NicknamedOperation;
+import io.swagger.resources.*;
 
+import io.swagger.util.Json;
 import org.testng.annotations.Test;
 
 import java.util.ArrayList;
@@ -541,4 +518,46 @@ public void scanResourceWithApiOperationNickname() {
 
         assertEquals(op.getOperationId(), "getMyNicknameTest");
     }
+
+    @Test(description = "scan a resource with operation post example")
+    public void scanClassWithExamplePost() {
+        Swagger swagger = getSwagger(ClassWithExamplePost.class);
+        Parameter param = swagger.getPaths().get("/external/info").getPost().getParameters().get(0);
+        BodyParameter bp = (BodyParameter) param;
+        assertNotNull(bp.getExamples());
+        assertTrue(bp.getExamples().size() == 1);
+        String value = bp.getExamples().get("application/json");
+        assertEquals("[\"a\",\"b\"]", value);
+    }
+
+    @Test(description = "scan a resource with operation implicit post example")
+    public void scanClassWithImplicitExamplePost() {
+        Swagger swagger = getSwagger(ClassWithExamplePost.class);
+        Parameter param = swagger.getPaths().get("/external/info2").getPost().getParameters().get(0);
+        BodyParameter bp = (BodyParameter) param;
+        assertNotNull(bp.getExamples());
+        assertTrue(bp.getExamples().size() == 1);
+        String value = bp.getExamples().get("application/json");
+        assertEquals("[\"a\",\"b\"]", value);
+    }
+
+    @Test(description = "scan a resource with query param example")
+    public void scanClassWithExampleQuery() {
+        Swagger swagger = getSwagger(ClassWithExamplePost.class);
+        Parameter param = swagger.getPaths().get("/external/info").getGet().getParameters().get(0);
+        QueryParameter bp = (QueryParameter) param;
+        assertNotNull(bp.getExample());
+        Object value = bp.getExample();
+        assertEquals("a,b,c", value);
+    }
+
+    @Test(description = "scan a resource with implicit operation query example")
+    public void scanClassWithImplicitExampleQuery() {
+        Swagger swagger = getSwagger(ClassWithExamplePost.class);
+        Parameter param = swagger.getPaths().get("/external/info2").getGet().getParameters().get(0);
+        QueryParameter bp = (QueryParameter) param;
+        assertNotNull(bp.getExample());
+        Object value = bp.getExample();
+        assertEquals("77", value);
+    }
 }

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

@@ -0,0 +1,58 @@
+package io.swagger.resources;
+
+import io.swagger.annotations.*;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.QueryParam;
+import java.util.ArrayList;
+
+@Api("/external/info/")
+public class ClassWithExamplePost {
+    @ApiOperation(value = "test")
+    @POST
+    @Path("external/info")
+    public void postTest(@ApiParam(value = "test",
+            examples = @Example(value = {
+                    @ExampleProperty(mediaType="application/json", value="[\"a\",\"b\"]")
+            })) ArrayList<String> tenantId) {
+        return;
+    }
+
+    @ApiOperation(value = "test")
+    @POST
+    @Path("external/info2")
+    @ApiImplicitParams({
+            @ApiImplicitParam(
+                    paramType = "body",
+                    name = "myPody",
+                    dataType = "[Ljava.lang.String;",
+                    examples = @Example(value = {
+                    @ExampleProperty(mediaType="application/json", value="[\"a\",\"b\"]")}))
+    })
+    public void implicitPostTest() {
+        return;
+    }
+
+    @ApiOperation(value = "test")
+    @GET
+    @Path("external/info")
+    public void queryExample(@ApiParam(value = "test",
+            example = "a,b,c") @QueryParam("tenantId") ArrayList<String> tenantId) {
+        return;
+    }
+
+    @ApiOperation(value = "test")
+    @GET
+    @Path("external/info2")
+    @ApiImplicitParams({
+            @ApiImplicitParam(
+                    paramType = "query",
+                    name = "myId",
+                    dataType = "java.lang.Long",
+                    example = "77") })
+    public void implicitQueryExample() {
+        return;
+    }
+}