You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2017/11/03 09:08:43 UTC
[camel] branch master updated: CAMEL-11908: Add support for
specifying examples in rest-dsl swagger api-doc
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 <cl...@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" <co...@camel.apache.org>'].