camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From davscl...@apache.org
Subject [camel] branch master updated: CAMEL-11908: Add support for specifying examples in rest-dsl swagger api-doc
Date Fri, 03 Nov 2017 09:08:43 GMT
This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/master by this push:
     new 010b55b  CAMEL-11908: Add support for specifying examples in rest-dsl swagger api-doc
010b55b is described below

commit 010b55b0547260814d0479f60e07a890434b0880
Author: Claus Ibsen <claus.ibsen@gmail.com>
AuthorDate: Fri Nov 3 10:08:26 2017 +0100

    CAMEL-11908: Add support for specifying examples in rest-dsl swagger api-doc
---
 .../model/rest/RestOperationParamDefinition.java   | 40 ++++++++++-
 .../RestOperationResponseHeaderDefinition.java     | 28 +++++++-
 .../rest/RestOperationResponseMsgDefinition.java   | 30 ++++++--
 .../apache/camel/swagger/RestSwaggerReader.java    | 81 ++++++++++++++++++----
 .../camel/swagger/RestSwaggerReaderTest.java       | 14 ++--
 5 files changed, 165 insertions(+), 28 deletions(-)

diff --git a/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationParamDefinition.java
b/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationParamDefinition.java
index e98e7c1..94335c3 100644
--- a/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationParamDefinition.java
+++ b/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationParamDefinition.java
@@ -28,7 +28,7 @@ import javax.xml.bind.annotation.XmlRootElement;
 import javax.xml.bind.annotation.XmlTransient;
 
 import org.apache.camel.spi.Metadata;
-import org.apache.camel.util.ObjectHelper;
+import org.apache.camel.util.StringHelper;
 
 /**
  * To specify the rest operation parameters using Swagger.
@@ -82,6 +82,9 @@ public class RestOperationParamDefinition {
     @Metadata(defaultValue = "")
     private String access;
 
+    @XmlElement(name = "examples")
+    private List<RestPropertyDefinition> examples;
+
     public RestOperationParamDefinition() {
     }
 
@@ -213,6 +216,17 @@ public class RestOperationParamDefinition {
         this.access = access;
     }
 
+    public List<RestPropertyDefinition> getExamples() {
+        return examples;
+    }
+
+    /**
+     * Sets the Swagger Parameter examples.
+     */
+    public void setExamples(List<RestPropertyDefinition> examples) {
+        this.examples = examples;
+    }
+
     /**
      * Name of the parameter.
      * <p/>
@@ -308,11 +322,33 @@ public class RestOperationParamDefinition {
     }
 
     /**
+     * Adds a body example with the given content-type
+     */
+    public RestOperationParamDefinition example(String contentType, String example) {
+        if (examples == null) {
+            examples = new ArrayList<>();
+        }
+        examples.add(new RestPropertyDefinition(contentType, example));
+        return this;
+    }
+
+    /**
+     * Adds a single example
+     */
+    public RestOperationParamDefinition example(String example) {
+        if (examples == null) {
+            examples = new ArrayList<>();
+        }
+        examples.add(new RestPropertyDefinition("", example));
+        return this;
+    }
+
+    /**
      * Ends the configuration of this parameter
      */
     public RestDefinition endParam() {
         // name is mandatory
-        ObjectHelper.notEmpty(name, "name");
+        StringHelper.notEmpty(name, "name");
         verb.getParams().add(this);
         return verb.getRest();
     }
diff --git a/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseHeaderDefinition.java
b/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseHeaderDefinition.java
index 00b488d..b3849c7 100644
--- a/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseHeaderDefinition.java
+++ b/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseHeaderDefinition.java
@@ -28,7 +28,7 @@ import javax.xml.bind.annotation.XmlRootElement;
 import javax.xml.bind.annotation.XmlTransient;
 
 import org.apache.camel.spi.Metadata;
-import org.apache.camel.util.ObjectHelper;
+import org.apache.camel.util.StringHelper;
 
 /**
  * To specify the rest operation response headers using Swagger.
@@ -66,6 +66,9 @@ public class RestOperationResponseHeaderDefinition {
     @XmlElement(name = "value")
     private List<String> allowableValues;
 
+    @XmlAttribute
+    private String example;
+
     public RestOperationResponseHeaderDefinition(RestOperationResponseMsgDefinition response)
{
         this();
         this.response = response;
@@ -143,6 +146,17 @@ public class RestOperationResponseHeaderDefinition {
         return new ArrayList<String>();
     }
 
+    public String getExample() {
+        return example;
+    }
+
+    /**
+     * Sets the Swagger example
+     */
+    public void setExample(String example) {
+        this.example = example;
+    }
+
     /**
      * Sets the Swagger Parameter list of allowable values.
      */
@@ -209,12 +223,20 @@ public class RestOperationResponseHeaderDefinition {
     }
 
     /**
+     * Sets an example of this header.
+     */
+    public RestOperationResponseHeaderDefinition example(String example) {
+        setExample(example);
+        return this;
+    }
+
+    /**
      * Ends the configuration of this header
      */
     public RestOperationResponseMsgDefinition endHeader() {
         // name and type is mandatory
-        ObjectHelper.notEmpty(name, "name");
-        ObjectHelper.notEmpty(dataType, "dataType");
+        StringHelper.notEmpty(name, "name");
+        StringHelper.notEmpty(dataType, "dataType");
         return response;
     }
 
diff --git a/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseMsgDefinition.java
b/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseMsgDefinition.java
index b7d0a57..ecbf064 100644
--- a/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseMsgDefinition.java
+++ b/camel-core/src/main/java/org/apache/camel/model/rest/RestOperationResponseMsgDefinition.java
@@ -26,7 +26,7 @@ import javax.xml.bind.annotation.XmlRootElement;
 import javax.xml.bind.annotation.XmlTransient;
 
 import org.apache.camel.spi.Metadata;
-import org.apache.camel.util.ObjectHelper;
+import org.apache.camel.util.StringHelper;
 
 /**
  * To specify the rest operation response messages using Swagger.
@@ -55,6 +55,9 @@ public class RestOperationResponseMsgDefinition {
     @XmlElement(name = "header")
     private List<RestOperationResponseHeaderDefinition> headers;
 
+    @XmlElement(name = "examples")
+    private List<RestPropertyDefinition> examples;
+
     public RestOperationResponseMsgDefinition(VerbDefinition verb) {
         this();
         this.verb = verb;
@@ -97,6 +100,14 @@ public class RestOperationResponseMsgDefinition {
         this.headers = headers;
     }
 
+    public List<RestPropertyDefinition> getExamples() {
+        return examples;
+    }
+
+    public void setExamples(List<RestPropertyDefinition> examples) {
+        this.examples = examples;
+    }
+
     /**
      * The response code such as a HTTP status code.
      */
@@ -131,11 +142,22 @@ public class RestOperationResponseMsgDefinition {
     }
 
     /**
+     * Adds an example
+     */
+    public RestOperationResponseMsgDefinition example(String key, String example) {
+        if (examples == null) {
+            examples = new ArrayList<>();
+        }
+        examples.add(new RestPropertyDefinition(key, example));
+        return this;
+    }
+
+    /**
      * Adds a response header
      */
     public RestOperationResponseHeaderDefinition header(String name) {
         if (headers == null) {
-            headers = new ArrayList<RestOperationResponseHeaderDefinition>();
+            headers = new ArrayList<>();
         }
         RestOperationResponseHeaderDefinition header = new RestOperationResponseHeaderDefinition(this);
         header.setName(name);
@@ -148,8 +170,8 @@ public class RestOperationResponseMsgDefinition {
      */
     public RestDefinition endResponseMessage() {
         // code and message is mandatory
-        ObjectHelper.notEmpty(code, "code");
-        ObjectHelper.notEmpty(message, "message");
+        StringHelper.notEmpty(code, "code");
+        StringHelper.notEmpty(message, "message");
         verb.getResponseMsgs().add(this);
         return verb.getRest();
     }
diff --git a/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerReader.java
b/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerReader.java
index 3bd5144..aa2122e 100644
--- a/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerReader.java
+++ b/components/camel-swagger-java/src/main/java/org/apache/camel/swagger/RestSwaggerReader.java
@@ -59,6 +59,7 @@ import org.apache.camel.model.rest.RestOperationParamDefinition;
 import org.apache.camel.model.rest.RestOperationResponseHeaderDefinition;
 import org.apache.camel.model.rest.RestOperationResponseMsgDefinition;
 import org.apache.camel.model.rest.RestParamType;
+import org.apache.camel.model.rest.RestPropertyDefinition;
 import org.apache.camel.model.rest.VerbDefinition;
 import org.apache.camel.spi.ClassResolver;
 import org.apache.camel.util.FileUtil;
@@ -250,7 +251,9 @@ public class RestSwaggerReader {
 
                 if (parameter != null) {
                     parameter.setName(param.getName());
-                    parameter.setDescription(param.getDescription());
+                    if (ObjectHelper.isNotEmpty(param.getDescription())) {
+                        parameter.setDescription(param.getDescription());
+                    }
                     parameter.setRequired(param.getRequired());
 
                     // set type on parameter
@@ -290,12 +293,17 @@ public class RestSwaggerReader {
                         }
                     }
 
-                    // set default value on parameter
                     if (parameter instanceof AbstractSerializableParameter) {
                         AbstractSerializableParameter qp = (AbstractSerializableParameter)
parameter;
-                        if (param.getDefaultValue() != null) {
+                        // set default value on parameter
+                        if (ObjectHelper.isNotEmpty(param.getDefaultValue())) {
                             qp.setDefaultValue(param.getDefaultValue());
                         }
+                        // add examples
+                        if (param.getExamples() != null && param.getExamples().size()
>= 1) {
+                            // we can only set one example on the parameter
+                            qp.example(param.getExamples().get(0).getValue());
+                        }
                     }
 
                     // set schema on body parameter
@@ -319,6 +327,12 @@ public class RestSwaggerReader {
                                 }
                             }
                         }
+                        // add examples
+                        if (param.getExamples() != null) {
+                            for (RestPropertyDefinition prop : param.getExamples()) {
+                                bp.example(prop.getKey(), prop.getValue());
+                            }
+                        }
                     }
 
                     op.addParameter(parameter);
@@ -360,7 +374,9 @@ public class RestSwaggerReader {
                 Property prop = modelTypeAsProperty(msg.getResponseModel(), swagger);
                 response.setSchema(prop);
             }
-            response.setDescription(msg.getMessage());
+            if (ObjectHelper.isNotEmpty(msg.getMessage())) {
+                response.setDescription(msg.getMessage());
+            }
 
             // add headers
             if (msg.getHeaders() != null) {
@@ -374,6 +390,10 @@ public class RestSwaggerReader {
                         if (header.getAllowableValues() != null) {
                             sp.setEnum(header.getAllowableValues());
                         }
+                        // add example
+                        if (header.getExample() != null) {
+                            sp.example(header.getExample());
+                        }
                         response.addHeader(name, sp);
                     } else if ("int".equals(type) || "integer".equals(type)) {
                         IntegerProperty ip = new IntegerProperty();
@@ -382,12 +402,16 @@ public class RestSwaggerReader {
 
                         List<Integer> values;
                         if (!header.getAllowableValues().isEmpty()) {
-                            values = new ArrayList<Integer>();
+                            values = new ArrayList<>();
                             for (String text : header.getAllowableValues()) {
                                 values.add(Integer.valueOf(text));
                             }
                             ip.setEnum(values);
                         }
+                        // add example
+                        if (header.getExample() != null) {
+                            ip.example(Integer.valueOf(header.getExample()));
+                        }
                         response.addHeader(name, ip);
                     } else if ("long".equals(type)) {
                         LongProperty lp = new LongProperty();
@@ -396,27 +420,35 @@ public class RestSwaggerReader {
 
                         List<Long> values;
                         if (!header.getAllowableValues().isEmpty()) {
-                            values = new ArrayList<Long>();
+                            values = new ArrayList<>();
                             for (String text : header.getAllowableValues()) {
                                 values.add(Long.valueOf(text));
                             }
                             lp.setEnum(values);
                         }
+                        // add example
+                        if (header.getExample() != null) {
+                            lp.example(Long.valueOf(header.getExample()));
+                        }
                         response.addHeader(name, lp);
                     } else if ("float".equals(type)) {
-                        FloatProperty lp = new FloatProperty();
-                        lp.setName(name);
-                        lp.setDescription(header.getDescription());
+                        FloatProperty fp = new FloatProperty();
+                        fp.setName(name);
+                        fp.setDescription(header.getDescription());
 
                         List<Float> values;
                         if (!header.getAllowableValues().isEmpty()) {
-                            values = new ArrayList<Float>();
+                            values = new ArrayList<>();
                             for (String text : header.getAllowableValues()) {
                                 values.add(Float.valueOf(text));
                             }
-                            lp.setEnum(values);
+                            fp.setEnum(values);
                         }
-                        response.addHeader(name, lp);
+                        // add example
+                        if (header.getExample() != null) {
+                            fp.example(Float.valueOf(header.getExample()));
+                        }
+                        response.addHeader(name, fp);
                     } else if ("double".equals(type)) {
                         DoubleProperty dp = new DoubleProperty();
                         dp.setName(name);
@@ -424,22 +456,32 @@ public class RestSwaggerReader {
 
                         List<Double> values;
                         if (!header.getAllowableValues().isEmpty()) {
-                            values = new ArrayList<Double>();
+                            values = new ArrayList<>();
                             for (String text : header.getAllowableValues()) {
                                 values.add(Double.valueOf(text));
                             }
                             dp.setEnum(values);
                         }
+                        // add example
+                        if (header.getExample() != null) {
+                            dp.example(Double.valueOf(header.getExample()));
+                        }
                         response.addHeader(name, dp);
                     } else if ("boolean".equals(type)) {
                         BooleanProperty bp = new BooleanProperty();
                         bp.setName(name);
                         bp.setDescription(header.getDescription());
+                        // add example
+                        if (header.getExample() != null) {
+                            bp.example(Boolean.valueOf(header.getExample()));
+                        }
                         response.addHeader(name, bp);
                     } else if ("array".equals(type)) {
                         ArrayProperty ap = new ArrayProperty();
                         ap.setName(name);
-                        ap.setDescription(header.getDescription());
+                        if (ObjectHelper.isNotEmpty(header.getDescription())) {
+                            ap.setDescription(header.getDescription());
+                        }
                         if (header.getArrayType() != null) {
                             if (header.getArrayType().equalsIgnoreCase("string")) {
                                 ap.setItems(new StringProperty());
@@ -460,11 +502,22 @@ public class RestSwaggerReader {
                                 ap.setItems(new BooleanProperty());
                             }
                         }
+                        // add example
+                        if (header.getExample() != null) {
+                            ap.example(header.getExample());
+                        }
                         response.addHeader(name, ap);
                     }
                 }
             }
 
+            // add examples
+            if (msg.getExamples() != null) {
+                for (RestPropertyDefinition prop : msg.getExamples()) {
+                    response.example(prop.getKey(), prop.getValue());
+                }
+            }
+
             op.addResponse(msg.getCode(), response);
         }
 
diff --git a/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderTest.java
b/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderTest.java
index 31dc0b3..42ec223 100644
--- a/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderTest.java
+++ b/components/camel-swagger-java/src/test/java/org/apache/camel/swagger/RestSwaggerReaderTest.java
@@ -44,14 +44,15 @@ public class RestSwaggerReaderTest extends CamelTestSupport {
             public void configure() throws Exception {
                 rest("/hello").consumes("application/json").produces("application/json")
                         .get("/hi/{name}").description("Saying hi")
-                            .param().name("name").type(RestParamType.path).dataType("string").description("Who
is it").endParam()
+                            .param().name("name").type(RestParamType.path).dataType("string").description("Who
is it").example("Donald Duck").endParam()
                             .to("log:hi")
                         .get("/bye/{name}").description("Saying bye")
-                            .param().name("name").type(RestParamType.path).dataType("string").description("Who
is it").endParam()
-                            .responseMessage().code(200).message("A reply number").responseModel(float.class).endResponseMessage()
+                            .param().name("name").type(RestParamType.path).dataType("string").description("Who
is it").example("Donald Duck").endParam()
+                            .responseMessage().code(200).message("A reply number").responseModel(float.class)
+                                .example("success", "123").example("error", "-1").endResponseMessage()
                             .to("log:bye")
                         .post("/bye").description("To update the greeting message").consumes("application/xml").produces("application/xml")
-                            .param().name("greeting").type(RestParamType.body).dataType("string").description("Message
to use as greeting").endParam()
+                            .param().name("greeting").type(RestParamType.body).dataType("string").description("Message
to use as greeting").example("application/xml","<hello>Hi</hello>").endParam()
                             .to("log:bye");
             }
         };
@@ -74,7 +75,6 @@ public class RestSwaggerReaderTest extends CamelTestSupport {
         String json = mapper.writeValueAsString(swagger);
 
         log.info(json);
-        System.out.println(json);
 
         assertTrue(json.contains("\"host\" : \"localhost:8080\""));
         assertTrue(json.contains("\"basePath\" : \"/api\""));
@@ -84,6 +84,10 @@ public class RestSwaggerReaderTest extends CamelTestSupport {
         assertTrue(json.contains("\"/hello/hi/{name}\""));
         assertTrue(json.contains("\"type\" : \"number\""));
         assertTrue(json.contains("\"format\" : \"float\""));
+        assertTrue(json.contains("\"application/xml\" : \"<hello>Hi</hello>\""));
+        assertTrue(json.contains("\"x-example\" : \"Donald Duck\""));
+        assertTrue(json.contains("\"success\" : \"123\""));
+        assertTrue(json.contains("\"error\" : \"-1\""));
 
         context.stop();
     }

-- 
To stop receiving notification emails like this one, please contact
['"commits@camel.apache.org" <commits@camel.apache.org>'].

Mime
View raw message