Swagger documentation comments

vojtechhabarta · vojtechhabarta · commit f76bc8d77954 · 2017-03-15T23:02:24.000+01:00
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/compiler/ModelCompiler.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/compiler/ModelCompiler.java
@@ -385,9 +385,10 @@ private static Map<String, Long> groupingByMethodName(List<JaxrsMethodModel> met
     private TsMethodModel processJaxrsMethod(SymbolTable symbolTable, String pathPrefix, Symbol responseSymbol, JaxrsMethodModel method, boolean createLongName, TsType optionsType, boolean implement) {
         final String path = Utils.joinPath(pathPrefix, method.getPath());
         final PathTemplate pathTemplate = PathTemplate.parse(path);
-        final List<String> comments = new ArrayList<>();
-        comments.add("HTTP " + method.getHttpMethod() + " /" + path);
-        comments.add("Java method: " + method.getOriginClass().getName() + "." + method.getName());
+        final List<String> comments = Utils.concat(method.getComments(), Arrays.asList(
+            "HTTP " + method.getHttpMethod() + " /" + path,
+            "Java method: " + method.getOriginClass().getName() + "." + method.getName()
+        ));
         final List<TsParameterModel> parameters = new ArrayList<>();
         // path params
         for (MethodParameterModel parameter : method.getPathParams()) {
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/Javadoc.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/Javadoc.java
@@ -2,6 +2,7 @@
 package cz.habarta.typescript.generator.parser;
 
 import cz.habarta.typescript.generator.compiler.EnumMemberModel;
+import cz.habarta.typescript.generator.util.Utils;
 import cz.habarta.typescript.generator.xmldoclet.Class;
 import cz.habarta.typescript.generator.xmldoclet.Enum;
 import cz.habarta.typescript.generator.xmldoclet.EnumConstant;
@@ -73,7 +74,7 @@ private BeanModel enrichBean(BeanModel bean, String beanComment, List<TagInfo> t
             final PropertyModel enrichedProperty = enrichProperty(property, dFields, dMethods);
             enrichedProperties.add(enrichedProperty);
         }
-        return bean.withProperties(enrichedProperties).withComments(concat(getComments(beanComment, tags), bean.getComments()));
+        return bean.withProperties(enrichedProperties).withComments(Utils.concat(getComments(beanComment, tags), bean.getComments()));
     }
 
     private PropertyModel enrichProperty(PropertyModel property, List<Field> dFields, List<Method> dMethods) {
@@ -104,7 +105,7 @@ private <T> EnumModel<T> enrichEnum(EnumModel<T> enumModel) {
         }
         final String enumComment = dEnum != null ? dEnum.getComment() : null;
         final List<TagInfo> tags = dEnum != null ? dEnum.getTag() : null;
-        return enumModel.withMembers(enrichedMembers).withComments(concat(getComments(enumComment, tags), enumModel.getComments()));
+        return enumModel.withMembers(enrichedMembers).withComments(Utils.concat(getComments(enumComment, tags), enumModel.getComments()));
     }
 
     private <T> EnumMemberModel<T> enrichEnumMember(EnumMemberModel<T> enumMember, Enum dEnum) {
@@ -216,13 +217,4 @@ private static List<String> splitMultiline(String comments) {
         return result;
     }
 
-    private static <T> List<T> concat(List<? extends T> list1, List<? extends T> list2) {
-        if (list1 == null && list2 == null) {
-            return null;
-        }
-        final List<T> result = new ArrayList<>();
-        if (list1 != null) result.addAll(list1);
-        if (list2 != null) result.addAll(list2);
-        return result;
-    }
 }
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/JaxrsApplicationParser.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/JaxrsApplicationParser.java
@@ -130,8 +130,10 @@ private void parseResourceMethod(Result result, ResourceContext context, Class<?
                     ? new SwaggerOperation()
                     : Swagger.parseSwaggerAnnotations(method);
             if (swaggerOperation.possibleResponses != null) {
-                for (Type response : swaggerOperation.possibleResponses) {
-                    foundType(result, response, resourceClass, method.getName());
+                for (SwaggerResponse response : swaggerOperation.possibleResponses) {
+                    if (response.responseType != null) {
+                        foundType(result, response.responseType, resourceClass, method.getName());
+                    }
                 }
             }
             if (swaggerOperation.hidden) {
@@ -168,8 +170,8 @@ private void parseResourceMethod(Result result, ResourceContext context, Class<?
             if (returnType == void.class) {
                 modelReturnType = returnType;
             } else if (returnType == Response.class) {
-                if (swaggerOperation.response != null) {
-                    modelReturnType = swaggerOperation.response;
+                if (swaggerOperation.responseType != null) {
+                    modelReturnType = swaggerOperation.responseType;
                     foundType(result, modelReturnType, resourceClass, method.getName());
                 } else {
                     modelReturnType = Object.class;
@@ -182,8 +184,10 @@ private void parseResourceMethod(Result result, ResourceContext context, Class<?
                 modelReturnType = genericReturnType;
                 foundType(result, modelReturnType, resourceClass, method.getName());
             }
+            // comments
+            final List<String> comments = Swagger.getOperationComments(swaggerOperation);
             // create method
-            model.getMethods().add(new JaxrsMethodModel(resourceClass, method.getName(), modelReturnType, httpMethod.value(), context.path, pathParams, queryParams, entityParameter));
+            model.getMethods().add(new JaxrsMethodModel(resourceClass, method.getName(), modelReturnType, httpMethod.value(), context.path, pathParams, queryParams, entityParameter, comments));
         }
         // JAX-RS specification - 3.4.1 Sub Resources
         if (pathAnnotation != null && httpMethod == null) {
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/JaxrsMethodModel.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/JaxrsMethodModel.java
@@ -14,8 +14,9 @@ public class JaxrsMethodModel extends MethodModel {
     private final MethodParameterModel entityParam;
 
     public JaxrsMethodModel(Class<?> originClass, String name, Type returnType,
-            String httpMethod, String path, List<MethodParameterModel> pathParams, List<MethodParameterModel> queryParams, MethodParameterModel entityParam) {
-        super(originClass, name, null, returnType);
+            String httpMethod, String path, List<MethodParameterModel> pathParams, List<MethodParameterModel> queryParams, MethodParameterModel entityParam,
+            List<String> comments) {
+        super(originClass, name, null, returnType, comments);
         this.httpMethod = httpMethod;
         this.path = path;
         this.pathParams = pathParams;
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/MethodModel.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/MethodModel.java
@@ -12,12 +12,14 @@ public class MethodModel {
     private final String name;
     private final List<MethodParameterModel> parameters;
     private final Type returnType;
+    private final List<String> comments;
 
-    public MethodModel(Class<?> originClass, String name, List<MethodParameterModel> parameters, Type returnType) {
+    public MethodModel(Class<?> originClass, String name, List<MethodParameterModel> parameters, Type returnType, List<String> comments) {
         this.originClass = originClass;
         this.name = name;
         this.parameters = parameters != null ? parameters : Collections.<MethodParameterModel>emptyList();
         this.returnType = returnType;
+        this.comments = comments;
     }
 
     public Class<?> getOriginClass() {
@@ -36,4 +38,8 @@ public Type getReturnType() {
         return returnType;
     }
 
+    public List<String> getComments() {
+        return comments;
+    }
+
 }
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/ModelParser.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/ModelParser.java
@@ -30,7 +30,8 @@ public Model parseModel(Type type) {
     public Model parseModel(List<SourceType<Type>> types) {
         typeQueue.addAll(types);
         final Model model = parseQueue();
-        final Model modelWithJavadoc = javadoc.enrichModel(model);
+        final Model modelWithSwaggerDoc = Swagger.enrichModel(model);
+        final Model modelWithJavadoc = javadoc.enrichModel(modelWithSwaggerDoc);
         return modelWithJavadoc;
     }
 
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/Swagger.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/Swagger.java
@@ -2,6 +2,7 @@
 package cz.habarta.typescript.generator.parser;
 
 import cz.habarta.typescript.generator.util.Utils;
+import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
 import java.util.*;
 
@@ -17,21 +18,23 @@ static SwaggerOperation parseSwaggerAnnotations(Method method) {
                 final Class<?> response = Utils.getAnnotationElementValue(apiOperation, "response", Class.class);
                 final String responseContainer = Utils.getAnnotationElementValue(apiOperation, "responseContainer", String.class);
                 if (responseContainer == null || responseContainer.isEmpty()) {
-                    swaggerOperation.response = response;
+                    swaggerOperation.responseType = response;
                 } else {
                     switch (responseContainer) {
                         case "List":
-                            swaggerOperation.response = Utils.createParameterizedType(List.class, response);
+                            swaggerOperation.responseType = Utils.createParameterizedType(List.class, response);
                             break;
                         case "Set":
-                            swaggerOperation.response = Utils.createParameterizedType(Set.class, response);
+                            swaggerOperation.responseType = Utils.createParameterizedType(Set.class, response);
                             break;
                         case "Map":
-                            swaggerOperation.response = Utils.createParameterizedType(Map.class, String.class, response);
+                            swaggerOperation.responseType = Utils.createParameterizedType(Map.class, String.class, response);
                             break;
                     }
                 }
                 swaggerOperation.hidden = Utils.getAnnotationElementValue(apiOperation, "hidden", Boolean.class);
+                swaggerOperation.comment = Utils.getAnnotationElementValue(apiOperation, "value", String.class);
+                swaggerOperation.comment = swaggerOperation.comment.isEmpty() ? null : swaggerOperation.comment;
             }
         }
         // @ApiResponses
@@ -40,11 +43,59 @@ static SwaggerOperation parseSwaggerAnnotations(Method method) {
             if (apiResponses != null) {
                 swaggerOperation.possibleResponses = new ArrayList<>();
                 for (Object apiResponse : apiResponses) {
-                    swaggerOperation.possibleResponses.add(Utils.getAnnotationElementValue(apiResponse, "response", Class.class));
+                    final SwaggerResponse response = new SwaggerResponse();
+                    response.code = Utils.getAnnotationElementValue(apiResponse, "code", Integer.class);
+                    response.comment = Utils.getAnnotationElementValue(apiResponse, "message", String.class);
+                    response.responseType = Utils.getAnnotationElementValue(apiResponse, "response", Class.class);
+                    swaggerOperation.possibleResponses.add(response);
                 }
             }
         }
         return swaggerOperation;
     }
 
+    static List<String> getOperationComments(SwaggerOperation operation) {
+        final List<String> comments = new ArrayList<>();
+        if (operation.comment != null) {
+            comments.add(operation.comment);
+        }
+        if (operation.possibleResponses != null) {
+            for (SwaggerResponse response : operation.possibleResponses) {
+                comments.add(String.format("Response code %s - %s", response.code, response.comment));
+            }
+        }
+        return comments.isEmpty() ? null : comments;
+    }
+
+    public static Model enrichModel(Model model) {
+        final List<BeanModel> dBeans = new ArrayList<>();
+        for (BeanModel bean : model.getBeans()) {
+            final BeanModel dBean = enrichBean(bean);
+            dBeans.add(dBean);
+        }
+        return new Model(dBeans, model.getEnums(), model.getJaxrsApplication());
+    }
+
+    private static BeanModel enrichBean(BeanModel bean) {
+        final List<PropertyModel> enrichedProperties = new ArrayList<>();
+        for (PropertyModel property : bean.getProperties()) {
+            final PropertyModel enrichedProperty = enrichProperty(property);
+            enrichedProperties.add(enrichedProperty);
+        }
+        final String comment = Utils.getAnnotationElementValue(bean.getOrigin(), "io.swagger.annotations.ApiModel", "description", String.class);
+        final List<String> comments = comment != null && !comment.isEmpty() ? Arrays.asList(comment) : null;
+        return bean.withProperties(enrichedProperties).withComments(Utils.concat(comments, bean.getComments()));
+    }
+
+    private static PropertyModel enrichProperty(PropertyModel property) {
+        if (property.getOriginalMember() instanceof AnnotatedElement) {
+            final AnnotatedElement annotatedElement = (AnnotatedElement) property.getOriginalMember();
+            final String comment = Utils.getAnnotationElementValue(annotatedElement, "io.swagger.annotations.ApiModelProperty", "value", String.class);
+            final List<String> comments = comment != null && !comment.isEmpty() ? Arrays.asList(comment) : null;
+            return property.withComments(Utils.concat(comments, property.getComments()));
+        } else {
+            return property;
+        }
+    }
+
 }
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/SwaggerOperation.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/SwaggerOperation.java
@@ -6,7 +6,8 @@
 
 
 public class SwaggerOperation {
-    public Type response;
-    public List<Type> possibleResponses;
+    public Type responseType;
+    public List<SwaggerResponse> possibleResponses;
     public boolean hidden;
+    public String comment;
 }
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/SwaggerResponse.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/parser/SwaggerResponse.java
@@ -0,0 +1,11 @@
+
+package cz.habarta.typescript.generator.parser;
+
+import java.lang.reflect.Type;
+
+
+public class SwaggerResponse {
+    public int code;
+    public String comment;
+    public Type responseType;
+}
diff --git a/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/util/Utils.java b/typescript-generator-core/src/main/java/cz/habarta/typescript/generator/util/Utils.java
@@ -71,9 +71,11 @@ public static <T> T getAnnotationElementValue(AnnotatedElement annotatedElement,
     }
 
     public static Object getAnnotation(AnnotatedElement annotatedElement, String annotationClassName) {
-        for (Annotation annotation : annotatedElement.getAnnotations()) {
-            if (annotation.annotationType().getName().equals(annotationClassName)) {
-                return annotation;
+        if (annotatedElement != null) {
+            for (Annotation annotation : annotatedElement.getAnnotations()) {
+                if (annotation.annotationType().getName().equals(annotationClassName)) {
+                    return annotation;
+                }
             }
         }
         return null;
@@ -139,6 +141,16 @@ public int hashCode() {
         };
     }
 
+    public static <T> List<T> concat(List<? extends T> list1, List<? extends T> list2) {
+        if (list1 == null && list2 == null) {
+            return null;
+        }
+        final List<T> result = new ArrayList<>();
+        if (list1 != null) result.addAll(list1);
+        if (list2 != null) result.addAll(list2);
+        return result;
+    }
+
     public static <T> List<T> listFromNullable(T item) {
         return item != null ? Arrays.asList(item) : Collections.<T>emptyList();
     }
diff --git a/typescript-generator-core/src/test/java/cz/habarta/typescript/generator/SwaggerTest.java b/typescript-generator-core/src/test/java/cz/habarta/typescript/generator/SwaggerTest.java
@@ -1,6 +1,8 @@
 
 package cz.habarta.typescript.generator;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiResponse;
 import io.swagger.annotations.ApiResponses;
@@ -32,6 +34,18 @@ public void test() {
         Assert.assertTrue(!output.contains("testHiddenOperation"));
     }
 
+    @Test
+    public void testDocumentation() {
+        final Settings settings = TestUtils.settings();
+        settings.generateJaxrsApplicationInterface = true;
+        final String output = new TypeScriptGenerator(settings).generateTypeScript(Input.from(DocumentedApplication.class));
+        Assert.assertTrue(output.contains("Documentation for operation 1."));
+        Assert.assertTrue(output.contains("Bad Request"));
+        Assert.assertTrue(output.contains("Not Found"));
+        Assert.assertTrue(output.contains("Documentation for the bean."));
+        Assert.assertTrue(output.contains("Documentation for property 1."));
+    }
+
     private static class TestApplication extends Application {
         @Override
         public Set<Class<?>> getClasses() {
@@ -86,4 +100,34 @@ private static class TestResponse {
     private static class TestError {
     }
 
+
+    private static class DocumentedApplication extends Application {
+        @Override
+        public Set<Class<?>> getClasses() {
+            return new LinkedHashSet<>(Arrays.<Class<?>>asList(DocumentedResource.class));
+        }
+    }
+
+    @Path("test")
+    private static class DocumentedResource {
+
+        @ApiOperation("Documentation for operation 1.")
+        @ApiResponses({
+            @ApiResponse(code = 400, message = "Bad Request"),
+            @ApiResponse(code = 404, message = "Not Found"),
+        })
+        @GET
+        public DocumentedBean documentedOperation1() {
+            return null;
+        }
+
+    }
+
+    @ApiModel(description = "Documentation for the bean.")
+    private static class DocumentedBean {
+
+        @ApiModelProperty("Documentation for property 1.")
+        public String property1;
+    }
+
 }

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`	`package cz.habarta.typescript.generator.parser;`
`3`	`3`
`4`	`4`	`import cz.habarta.typescript.generator.compiler.EnumMemberModel;`
	`5`	`+import cz.habarta.typescript.generator.util.Utils;`
`5`	`6`	`import cz.habarta.typescript.generator.xmldoclet.Class;`
`6`	`7`	`import cz.habarta.typescript.generator.xmldoclet.Enum;`
`7`	`8`	`import cz.habarta.typescript.generator.xmldoclet.EnumConstant;`
`@@ -73,7 +74,7 @@ private BeanModel enrichBean(BeanModel bean, String beanComment, List<TagInfo> t`
`73`	`74`	`final PropertyModel enrichedProperty = enrichProperty(property, dFields, dMethods);`
`74`	`75`	`enrichedProperties.add(enrichedProperty);`
`75`	`76`	`}`
`76`		`- return bean.withProperties(enrichedProperties).withComments(concat(getComments(beanComment, tags), bean.getComments()));`
	`77`	`+ return bean.withProperties(enrichedProperties).withComments(Utils.concat(getComments(beanComment, tags), bean.getComments()));`
`77`	`78`	`}`
`78`	`79`
`79`	`80`	`private PropertyModel enrichProperty(PropertyModel property, List<Field> dFields, List<Method> dMethods) {`
`@@ -104,7 +105,7 @@ private <T> EnumModel<T> enrichEnum(EnumModel<T> enumModel) {`
`104`	`105`	`}`
`105`	`106`	`final String enumComment = dEnum != null ? dEnum.getComment() : null;`
`106`	`107`	`final List<TagInfo> tags = dEnum != null ? dEnum.getTag() : null;`
`107`		`- return enumModel.withMembers(enrichedMembers).withComments(concat(getComments(enumComment, tags), enumModel.getComments()));`
	`108`	`+ return enumModel.withMembers(enrichedMembers).withComments(Utils.concat(getComments(enumComment, tags), enumModel.getComments()));`
`108`	`109`	`}`
`109`	`110`
`110`	`111`	`private <T> EnumMemberModel<T> enrichEnumMember(EnumMemberModel<T> enumMember, Enum dEnum) {`
`@@ -216,13 +217,4 @@ private static List<String> splitMultiline(String comments) {`
`216`	`217`	`return result;`
`217`	`218`	`}`
`218`	`219`
`219`		`- private static <T> List<T> concat(List<? extends T> list1, List<? extends T> list2) {`
`220`		`- if (list1 == null && list2 == null) {`
`221`		`- return null;`
`222`		`- }`
`223`		`- final List<T> result = new ArrayList<>();`
`224`		`- if (list1 != null) result.addAll(list1);`
`225`		`- if (list2 != null) result.addAll(list2);`
`226`		`- return result;`
`227`		`- }`
`228`	`220`	`}`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,8 @@ public Model parseModel(Type type) {`
`30`	`30`	`public Model parseModel(List<SourceType<Type>> types) {`
`31`	`31`	`typeQueue.addAll(types);`
`32`	`32`	`final Model model = parseQueue();`
`33`		`- final Model modelWithJavadoc = javadoc.enrichModel(model);`
	`33`	`+ final Model modelWithSwaggerDoc = Swagger.enrichModel(model);`
	`34`	`+ final Model modelWithJavadoc = javadoc.enrichModel(modelWithSwaggerDoc);`
`34`	`35`	`return modelWithJavadoc;`
`35`	`36`	`}`
`36`	`37`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,8 @@`
`6`	`6`
`7`	`7`
`8`	`8`	`public class SwaggerOperation {`
`9`		`- public Type response;`
`10`		`- public List<Type> possibleResponses;`
	`9`	`+ public Type responseType;`
	`10`	`+ public List<SwaggerResponse> possibleResponses;`
`11`	`11`	`public boolean hidden;`
	`12`	`+ public String comment;`
`12`	`13`	`}`
Original file line number	Diff line number	Diff line change
`@@ -71,9 +71,11 @@ public static <T> T getAnnotationElementValue(AnnotatedElement annotatedElement,`
`71`	`71`	`}`
`72`	`72`
`73`	`73`	`public static Object getAnnotation(AnnotatedElement annotatedElement, String annotationClassName) {`
`74`		`- for (Annotation annotation : annotatedElement.getAnnotations()) {`
`75`		`- if (annotation.annotationType().getName().equals(annotationClassName)) {`
`76`		`- return annotation;`
	`74`	`+ if (annotatedElement != null) {`
	`75`	`+ for (Annotation annotation : annotatedElement.getAnnotations()) {`
	`76`	`+ if (annotation.annotationType().getName().equals(annotationClassName)) {`
	`77`	`+ return annotation;`
	`78`	`+ }`
`77`	`79`	`}`
`78`	`80`	`}`
`79`	`81`	`return null;`
`@@ -139,6 +141,16 @@ public int hashCode() {`
`139`	`141`	`};`
`140`	`142`	`}`
`141`	`143`
	`144`	`+ public static <T> List<T> concat(List<? extends T> list1, List<? extends T> list2) {`
	`145`	`+ if (list1 == null && list2 == null) {`
	`146`	`+ return null;`
	`147`	`+ }`
	`148`	`+ final List<T> result = new ArrayList<>();`
	`149`	`+ if (list1 != null) result.addAll(list1);`
	`150`	`+ if (list2 != null) result.addAll(list2);`
	`151`	`+ return result;`
	`152`	`+ }`
	`153`	`+`
`142`	`154`	`public static <T> List<T> listFromNullable(T item) {`
`143`	`155`	`return item != null ? Arrays.asList(item) : Collections.<T>emptyList();`
`144`	`156`	`}`