[ONOS-2706] Insert Support for REST API model schema in Swagger UI
Change-Id: Iad158d90f203101fd23328f30f2507b7677a1997
diff --git a/tools/package/maven-plugin/src/main/java/org/onosproject/maven/OnosSwaggerMojo.java b/tools/package/maven-plugin/src/main/java/org/onosproject/maven/OnosSwaggerMojo.java
index ea84745..a75127a 100644
--- a/tools/package/maven-plugin/src/main/java/org/onosproject/maven/OnosSwaggerMojo.java
+++ b/tools/package/maven-plugin/src/main/java/org/onosproject/maven/OnosSwaggerMojo.java
@@ -18,6 +18,7 @@
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.google.common.base.Charsets;
import com.google.common.io.ByteStreams;
import com.google.common.io.Files;
import com.thoughtworks.qdox.JavaProjectBuilder;
@@ -124,11 +125,13 @@
ObjectNode root = initializeRoot();
ArrayNode tags = mapper.createArrayNode();
ObjectNode paths = mapper.createObjectNode();
+ ObjectNode definitions = mapper.createObjectNode();
root.set("tags", tags);
root.set("paths", paths);
+ root.set("definitions", definitions);
- builder.getClasses().forEach(jc -> processClass(jc, paths, tags));
+ builder.getClasses().forEach(jc -> processClass(jc, paths, tags, definitions));
if (paths.size() > 0) {
getLog().info("Generating ONOS REST API documentation...");
@@ -172,7 +175,7 @@
// Checks whether javaClass has a path tag associated with it and if it does
// processes its methods and creates a tag for the class on the root
- void processClass(JavaClass javaClass, ObjectNode paths, ArrayNode tags) {
+ void processClass(JavaClass javaClass, ObjectNode paths, ArrayNode tags, ObjectNode definitions) {
// If the class does not have a Path tag then ignore it
JavaAnnotation annotation = getPathAnnotation(javaClass);
if (annotation == null) {
@@ -199,7 +202,7 @@
ArrayNode tagArray = mapper.createArrayNode();
tagArray.add(tagPath);
- processAllMethods(javaClass, resourcePath, paths, tagArray);
+ processAllMethods(javaClass, resourcePath, paths, tagArray, definitions);
}
private JavaAnnotation getPathAnnotation(JavaClass javaClass) {
@@ -211,7 +214,7 @@
// Checks whether a class's methods are REST methods and then places all the
// methods under a specific path into the paths node
private void processAllMethods(JavaClass javaClass, String resourcePath,
- ObjectNode paths, ArrayNode tagArray) {
+ ObjectNode paths, ArrayNode tagArray, ObjectNode definitions) {
// map of the path to its methods represented by an ObjectNode
Map<String, ObjectNode> pathMap = new HashMap<>();
@@ -221,7 +224,7 @@
if (name.equals(POST) || name.equals(GET) || name.equals(DELETE) || name.equals(PUT)) {
// substring(12) removes "javax.ws.rs."
String method = annotation.getType().toString().substring(12).toLowerCase();
- processRestMethod(javaMethod, method, pathMap, resourcePath, tagArray);
+ processRestMethod(javaMethod, method, pathMap, resourcePath, tagArray, definitions);
}
});
});
@@ -236,9 +239,10 @@
private void processRestMethod(JavaMethod javaMethod, String method,
Map<String, ObjectNode> pathMap,
- String resourcePath, ArrayNode tagArray) {
+ String resourcePath, ArrayNode tagArray, ObjectNode definitions) {
String fullPath = resourcePath, consumes = "", produces = "",
comment = javaMethod.getComment();
+ DocletTag tag = javaMethod.getTagByName("rsModel");
for (JavaAnnotation annotation : javaMethod.getAnnotations()) {
String name = annotation.getType().getName();
if (name.equals(PATH)) {
@@ -256,12 +260,19 @@
methodNode.set("tags", tagArray);
addSummaryDescriptions(methodNode, comment);
- processParameters(javaMethod, methodNode);
+ addJsonSchemaDefinition(definitions, tag);
+ addJsonSchemaDefinition(definitions, tag);
+
+ processParameters(javaMethod, methodNode, method, tag);
processConsumesProduces(methodNode, "consumes", consumes);
processConsumesProduces(methodNode, "produces", produces);
-
- addResponses(methodNode);
+ if (tag == null || ((method.toLowerCase().equals("post") || method.toLowerCase().equals("put"))
+ && !(tag.getParameters().size() > 1))) {
+ addResponses(methodNode, tag, false);
+ } else {
+ addResponses(methodNode, tag, true);
+ }
ObjectNode operations = pathMap.get(fullPath);
if (operations == null) {
@@ -273,6 +284,24 @@
}
}
+ private void addJsonSchemaDefinition(ObjectNode definitions, DocletTag tag) {
+ File definitionsDirectory = new File(srcDirectory + "/src/main/resources/definitions");
+ if (tag != null) {
+ tag.getParameters().stream().forEach(param -> {
+ try {
+ File config = new File(definitionsDirectory.getAbsolutePath() + "/"
+ + param + ".json");
+ String lines = Files.readLines(config, Charsets.UTF_8).stream().reduce((t, u) -> t + u).
+ get();
+ definitions.putPOJO(param, lines);
+ } catch (IOException e) {
+ e.printStackTrace();
+ }
+ });
+
+ }
+ }
+
private void processConsumesProduces(ObjectNode methodNode, String type, String io) {
if (!io.equals("")) {
ArrayNode array = mapper.createArrayNode();
@@ -299,13 +328,19 @@
// Temporary solution to add responses to a method
// TODO Provide annotations in the web resources for responses and parse them
- private void addResponses(ObjectNode methodNode) {
+ private void addResponses(ObjectNode methodNode, DocletTag tag, boolean responseJson) {
ObjectNode responses = mapper.createObjectNode();
methodNode.set("responses", responses);
ObjectNode success = mapper.createObjectNode();
success.put("description", "successful operation");
responses.set("200", success);
+ if (tag != null && responseJson) {
+ ObjectNode schema = mapper.createObjectNode();
+ tag.getParameters().stream().forEach(
+ param -> schema.put("$ref", "#/definitions/" + param));
+ success.set("schema", schema);
+ }
ObjectNode defaultObj = mapper.createObjectNode();
defaultObj.put("description", "Unexpected error");
@@ -329,7 +364,7 @@
}
// Processes parameters of javaMethod and enters the proper key-values into the methodNode
- private void processParameters(JavaMethod javaMethod, ObjectNode methodNode) {
+ private void processParameters(JavaMethod javaMethod, ObjectNode methodNode, String method, DocletTag tag) {
ArrayNode parameters = mapper.createArrayNode();
methodNode.set("parameters", parameters);
boolean required = true;
@@ -346,7 +381,8 @@
if (pathType != null) { //the parameter is a path or query parameter
individualParameterNode.put("name",
- pathType.getNamedParameter("value").toString().replace("\"", ""));
+ pathType.getNamedParameter("value")
+ .toString().replace("\"", ""));
if (pathType.getType().getName().equals(PATH_PARAM)) {
individualParameterNode.put("in", "path");
} else if (pathType.getType().getName().equals(QUERY_PARAM)) {
@@ -357,10 +393,16 @@
individualParameterNode.put("name", annotationName);
individualParameterNode.put("in", "body");
- // TODO add actual hardcoded schemas and a type
- // body parameters must have a schema associated with them
- ArrayNode schema = mapper.createArrayNode();
- individualParameterNode.set("schema", schema);
+ // Adds the reference to the Json model for the input
+ // that goes in the post or put operation
+ if (tag != null && (method.toLowerCase().equals("post") ||
+ method.toLowerCase().equals("put"))) {
+ ObjectNode schema = mapper.createObjectNode();
+ tag.getParameters().stream().forEach(param -> {
+ schema.put("$ref", "#/definitions/" + param);
+ });
+ individualParameterNode.set("schema", schema);
+ }
}
for (DocletTag p : javaMethod.getTagsByName("param")) {
if (p.getValue().contains(annotationName)) {