Merge pull request #115 from SentryMan/openapi

Enhance OpenAPI generation

Author: rbygrave

README.md

@@ -1,7 +1,8 @@
 # avaje-http
 
-Http server and client libraries and code generation.
+HTTP server and client libraries via code generation.
 
+Documentation at [avaje.io/http](https://avaje.io/http/)
 ## Http Server
 
 A jax-rs style controllers with annotations (`@Path`, `@Get` ...)

http-api/src/main/java/io/avaje/http/api/OpenAPIResponse.java

@@ -0,0 +1,43 @@
+package io.avaje.http.api;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Specify endpoint response status code/description/type.
+ *
+ * <p>When not specified the default 2xx openAPI generation is based on the javadoc of the method.
+ * <p> Will not override the default 2xx generated openapi unless status code is 2xx
+ * <pre>{@code
+ * @Post("/post")
+ * @OpenAPIReturns(responseCode = "200", description = "from annotaion")
+ * @OpenAPIReturns(responseCode = "201")
+ * @OpenAPIReturns(responseCode = "500", description = "Some other Error", type=ErrorResponse.class)
+ * ResponseModel endpoint() {}
+ *
+ * }</pre>
+ */
+@Target(value = METHOD)
+@Retention(value = RUNTIME)
+@Repeatable(OpenAPIResponses.class)
+public @interface OpenAPIResponse {
+
+  /** the http status code of this response */
+  String responseCode();
+
+  /**
+   * The description of the return value. By default uses the @return javadoc of the method as the
+   * description
+   */
+  String description() default "";
+
+  /**
+   * The concrete type that that this endpoint returns. If status code is a 2xx code it will default
+   * to the return type of the method
+   */
+  Class<?> type() default Void.class;
+}

http-api/src/main/java/io/avaje/http/api/OpenAPIResponses.java

@@ -0,0 +1,18 @@
+package io.avaje.http.api;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Container for repeatable {@link OpenAPIResponse} annotation
+ *
+ * @see OpenAPIResponse
+ */
+@Target(value = METHOD)
+@Retention(value = RUNTIME)
+public @interface OpenAPIResponses {
+  OpenAPIResponse[] value();
+}

http-generator-core/src/main/java/io/avaje/http/generator/core/MethodReader.java

@@ -1,28 +1,36 @@
 package io.avaje.http.generator.core;
 
+import java.lang.annotation.Annotation;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ExecutableElement;
+import javax.lang.model.element.VariableElement;
+import javax.lang.model.type.ExecutableType;
+import javax.lang.model.type.TypeKind;
+import javax.lang.model.type.TypeMirror;
+import javax.validation.Valid;
+
 import io.avaje.http.api.Delete;
 import io.avaje.http.api.Form;
 import io.avaje.http.api.Get;
+import io.avaje.http.api.OpenAPIResponse;
+import io.avaje.http.api.OpenAPIResponses;
 import io.avaje.http.api.Patch;
 import io.avaje.http.api.Post;
 import io.avaje.http.api.Produces;
 import io.avaje.http.api.Put;
 import io.avaje.http.generator.core.javadoc.Javadoc;
 import io.avaje.http.generator.core.openapi.MethodDocBuilder;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import io.swagger.v3.oas.annotations.tags.Tags;
 
-import javax.lang.model.element.Element;
-import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.VariableElement;
-import javax.lang.model.type.ExecutableType;
-import javax.lang.model.type.TypeKind;
-import javax.lang.model.type.TypeMirror;
-import javax.validation.Valid;
-import java.lang.annotation.Annotation;
-import java.util.ArrayList;
-import java.util.List;
-
 public class MethodReader {
 
   private final ProcessingContext ctx;
@@ -46,13 +54,19 @@ public class MethodReader {
 
   private final String produces;
 
+  private final List<OpenAPIResponse> apiResponses;
+
   private final ExecutableType actualExecutable;
   private final List<? extends TypeMirror> actualParams;
 
   private final PathSegments pathSegments;
   private final boolean hasValid;
 
-  MethodReader(ControllerReader bean, ExecutableElement element, ExecutableType actualExecutable, ProcessingContext ctx) {
+  MethodReader(
+      ControllerReader bean,
+      ExecutableElement element,
+      ExecutableType actualExecutable,
+      ProcessingContext ctx) {
     this.ctx = ctx;
     this.bean = bean;
     this.element = element;
@@ -62,6 +76,7 @@ public class MethodReader {
     this.methodRoles = Util.findRoles(element);
     this.javadoc = Javadoc.parse(ctx.getDocComment(element));
     this.produces = produces(bean);
+    this.apiResponses = getApiResponses();
     initWebMethodViaAnnotation();
     if (isWebMethod()) {
       this.hasValid = findAnnotation(Valid.class) != null;
@@ -118,10 +133,22 @@ public Javadoc javadoc() {
   }
 
   private String produces(ControllerReader bean) {
-    final Produces produces = findAnnotation(Produces.class);
+    final var produces = findAnnotation(Produces.class);
     return (produces != null) ? produces.value() : bean.produces();
   }
 
+  private List<OpenAPIResponse> getApiResponses() {
+    final var container =
+        Optional.ofNullable(findAnnotation(OpenAPIResponses.class)).stream()
+            .map(OpenAPIResponses::value)
+            .flatMap(Arrays::stream);
+
+    return Stream.concat(container, Arrays.stream(element.getAnnotationsByType(OpenAPIResponse.class)))
+        .collect(Collectors.toList());
+
+
+  }
+
   public <A extends Annotation> A findAnnotation(Class<A> type) {
     A annotation = element.getAnnotation(type);
     if (annotation != null) {
@@ -216,6 +243,10 @@ public String produces() {
     return produces;
   }
 
+  public List<OpenAPIResponse> apiResponses() {
+    return apiResponses;
+  }
+
   public TypeMirror returnType() {
     if (actualExecutable != null) {
       return actualExecutable.getReturnType();
@@ -273,5 +304,4 @@ public String bodyName() {
     }
     return "body";
   }
-
 }

http-generator-core/src/main/java/io/avaje/http/generator/core/openapi/MethodDocBuilder.java

@@ -1,5 +1,8 @@
 package io.avaje.http.generator.core.openapi;
 
+import javax.lang.model.type.MirroredTypeException;
+import javax.lang.model.type.TypeMirror;
+
 import io.avaje.http.api.MediaType;
 import io.avaje.http.generator.core.MethodParam;
 import io.avaje.http.generator.core.MethodReader;
@@ -73,16 +76,46 @@ public void build() {
     ApiResponse response = new ApiResponse();
     response.setDescription(javadoc.getReturnDescription());
 
+    final var produces = methodReader.produces();
+    final var contentMediaType = (produces == null) ? MediaType.APPLICATION_JSON : produces;
+
     if (methodReader.isVoid()) {
       if (isEmpty(response.getDescription())) {
         response.setDescription("No content");
       }
     } else {
-      final String produces = methodReader.produces();
-      String contentMediaType = (produces == null) ? MediaType.APPLICATION_JSON : produces;
-      response.setContent(ctx.createContent(methodReader.returnType(), contentMediaType));
+    	response.setContent(ctx.createContent(methodReader.returnType(), contentMediaType));
+    }
+    var override2xx = false;
+    for (final var responseAnnotation : methodReader.apiResponses()) {
+      final var newResponse = new ApiResponse();
+
+      if (responseAnnotation.description().isEmpty()) {
+        newResponse.setDescription(response.getDescription());
+      } else {
+        newResponse.setDescription(responseAnnotation.description());
+      }
+
+      // if user wants to define their own 2xx status code
+      if (responseAnnotation.responseCode().startsWith("2")) {
+        newResponse.setContent(response.getContent());
+        override2xx = true;
+      }
+      TypeMirror returnType = null;
+      try {
+        // this will always throw
+        responseAnnotation.type();
+      } catch (final MirroredTypeException mte) {
+        returnType = mte.getTypeMirror();
+      }
+
+      if (!"java.lang.Void".equals(returnType.toString())) {
+        newResponse.setContent(ctx.createContent(returnType, contentMediaType));
+      }
+
+      responses.addApiResponse(responseAnnotation.responseCode(), newResponse);
     }
-    responses.addApiResponse(methodReader.statusCode(), response);
+    if (!override2xx) responses.addApiResponse(methodReader.statusCode(), response);
   }
 
   DocContext getContext() {

http-generator-core/src/main/java/io/avaje/http/generator/core/openapi/MethodParamDocBuilder.java

@@ -32,7 +32,7 @@ public MethodParamDocBuilder(MethodDocBuilder methodDoc, ElementReader param) {
     this.paramType = param.paramType();
     this.paramName = param.paramName();
     this.varName = param.varName();
-    this.rawType = param.rawType();
+    this.rawType = param.type().full();
     this.element = param.element();
   }
 

tests/test-javalin-jsonb/src/main/java/org/example/myapp/web/test/ErrorResponse.java

@@ -0,0 +1,7 @@
+package org.example.myapp.web.test;
+
+public class ErrorResponse {
+
+  public String id;
+  public String text;
+}

tests/test-javalin-jsonb/src/main/java/org/example/myapp/web/test/OpenAPIController.java

@@ -0,0 +1,81 @@
+package org.example.myapp.web.test;
+
+import java.util.List;
+
+import io.avaje.http.api.Controller;
+import io.avaje.http.api.Get;
+import io.avaje.http.api.MediaType;
+import io.avaje.http.api.OpenAPIResponse;
+import io.avaje.http.api.OpenAPIResponses;
+import io.avaje.http.api.Path;
+import io.avaje.http.api.Post;
+import io.avaje.http.api.Produces;
+import io.javalin.http.Context;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+@OpenAPIDefinition(
+    info =
+        @Info(
+            title = "Example service",
+            description = "Example Javalin controllers with Java and Maven"))
+@Controller
+@Path("openapi/")
+public class OpenAPIController {
+
+  /**
+   * Example of Open API Get (up to the first period is the summary). When using Javalin Context
+   * only <br>
+   * This Javadoc description is added to the generated openapi.json
+   *
+   * @return funny phrase (this part of the javadoc is added to the response desc)
+   */
+  @Get("/get")
+  @Produces(MediaType.TEXT_PLAIN)
+  @OpenAPIResponse(responseCode = "200", type = String.class)
+  void ctxEndpoint(Context ctx) {
+    ctx.contentType(MediaType.TEXT_PLAIN).result("healthlmao");
+  }
+
+  /**
+   * Standard Post. uses tag annotation to add tags to openapi json
+   *
+   * @param b the body (this is used for generated request body desc)
+   * @return the response body (from javadoc)
+   */
+  @Post("/post")
+  @Tag(name = "tag1", description = "this is added to openapi tags")
+  @OpenAPIResponse(responseCode = "200", description = "overrides @return javadoc description")
+  @OpenAPIResponse(responseCode = "201")
+  @OpenAPIResponse(
+      responseCode = "400",
+      description = "User not found (Will not have an associated response schema)")
+  @OpenAPIResponse(
+      responseCode = "500",
+      description = "Some other Error (Will have this error class as the response class)",
+      type = ErrorResponse.class)
+  Person testPost(Person b) {
+    return new Person(0, "baby");
+  }
+
+  /**
+   * Standard Post. The Deprecated annotation adds "deprecacted:true" to the generated json
+   *
+   * @param m the body
+   * @return the response body (from javadoc)
+   */
+  @Deprecated
+  @Post("/post1")
+  @OpenAPIResponses({
+    @OpenAPIResponse(responseCode = "400", description = "User not found"),
+    @OpenAPIResponse(
+        responseCode = "500",
+        description = "Some other Error",
+        type = ErrorResponse.class)
+  })
+  Person testPostl(List<Person> m) {
+
+    return new Person(0, "baby");
+  }
+}