use custom annotation

Author: SentryMan

http-api/src/main/java/io/avaje/http/api/OpenAPIReturns.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(OpenAPIReturnsContainer.class)
+public @interface OpenAPIReturns {
+
+  /** 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/OpenAPIReturnsContainer.java

@@ -0,0 +1,13 @@
+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;
+
+@Target(value = METHOD)
+@Retention(value = RUNTIME)
+public @interface OpenAPIReturnsContainer {
+  OpenAPIReturns[] value();
+}

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

@@ -15,6 +15,7 @@
 import io.avaje.http.api.Delete;
 import io.avaje.http.api.Form;
 import io.avaje.http.api.Get;
+import io.avaje.http.api.OpenAPIReturns;
 import io.avaje.http.api.Patch;
 import io.avaje.http.api.Post;
 import io.avaje.http.api.Produces;
@@ -48,7 +49,7 @@ public class MethodReader {
 
   private final String produces;
 
-  private final ApiResponse[] apiResponses;
+  private final OpenAPIReturns[] apiResponses;
 
   private final ExecutableType actualExecutable;
   private final List<? extends TypeMirror> actualParams;
@@ -131,8 +132,8 @@ private String produces(ControllerReader bean) {
     return (produces != null) ? produces.value() : bean.produces();
   }
 
-  private ApiResponse[] getApiResponses() {
-    return element.getAnnotationsByType(ApiResponse.class);
+  private OpenAPIReturns[] getApiResponses() {
+    return element.getAnnotationsByType(OpenAPIReturns.class);
   }
 
   public <A extends Annotation> A findAnnotation(Class<A> type) {
@@ -229,7 +230,7 @@ public String produces() {
     return produces;
   }
 
-  public ApiResponse[] apiResponses() {
+  public OpenAPIReturns[] apiResponses() {
     return apiResponses;
   }
 

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,28 +76,43 @@ 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())
+      if (responseAnnotation.description().isEmpty()) {
         newResponse.setDescription(response.getDescription());
-      else newResponse.setDescription(responseAnnotation.description());
+      } 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);
     }
     if (!override2xx) responses.addApiResponse(methodReader.statusCode(), response);