open-api: add examples for request/response body

jknack · jknack · commit fed823a93e08 · 2025-08-10T12:16:27.000-03:00
- format is: `{describe your json example here}`
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/JavaDocSetter.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/JavaDocSetter.java
@@ -48,7 +48,7 @@ public static void set(OperationExt operation, MethodDoc doc, List<String> param
     if (!doc.getExtensions().isEmpty()) {
       operation.setExtensions(doc.getExtensions());
     }
-    doc.getSecurityRequeriments().forEach(operation::addSecurityItem);
+    doc.getSecurityRequirements().forEach(operation::addSecurityItem);
     doc.getTags().forEach(operation::addTag);
     // Parameters
     for (var parameterName : parameterNames) {
@@ -63,16 +63,19 @@ public static void set(OperationExt operation, MethodDoc doc, List<String> param
         if (paramExt == null) {
           var body = operation.getRequestBody();
           if (body != null) {
+            body.setExamples(doc.getParameterExample(parameterName));
             body.setDescription(paramDoc);
           }
         } else {
+          paramExt.setExample(doc.getParameterExample(parameterName));
           paramExt.setDescription(paramDoc);
         }
       }
     }
     // return types
     var defaultResponse = operation.getDefaultResponse();
     if (defaultResponse != null) {
+      defaultResponse.setExamples(doc.getReturnExample());
       defaultResponse.setDescription(doc.getReturnDoc());
     }
     for (var throwsDoc : doc.getThrows().values()) {
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RequestBodyExt.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RequestBodyExt.java
@@ -11,6 +11,7 @@
 
 public class RequestBodyExt extends RequestBody {
 
+  @JsonIgnore private Object examples;
   @JsonIgnore private String javaType;
 
   @JsonIgnore private String contentType = MediaType.JSON;
@@ -34,4 +35,12 @@ public String getContentType() {
   public void setContentType(String contentType) {
     this.contentType = contentType;
   }
+
+  public Object getExamples() {
+    return examples;
+  }
+
+  public void setExamples(Object examples) {
+    this.examples = examples;
+  }
 }
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/ResponseExt.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/ResponseExt.java
@@ -29,6 +29,7 @@ public class ResponseExt extends ApiResponse {
           "io.smallrye.mutiny.Uni",
           "io.smallrye.mutiny.Multi");
 
+  @JsonIgnore private Object examples;
   @JsonIgnore private List<String> javaTypes = new ArrayList<>();
 
   @JsonIgnore private String code;
@@ -84,6 +85,14 @@ public void setCode(String code) {
     this.code = code;
   }
 
+  public Object getExamples() {
+    return examples;
+  }
+
+  public void setExamples(Object examples) {
+    this.examples = examples;
+  }
+
   @Override
   public String toString() {
     return getJavaType();
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RouteParser.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RouteParser.java
@@ -144,14 +144,14 @@ private void checkResponse(
       }
 
       if (content.isEmpty()) {
-        io.swagger.v3.oas.models.media.MediaType mediaTypeObject =
-            new io.swagger.v3.oas.models.media.MediaType();
+        var mediaTypeObject = new io.swagger.v3.oas.models.media.MediaType();
         String mediaType = operation.getProduces().stream().findFirst().orElse(MediaType.JSON);
         content.addMediaType(mediaType, mediaTypeObject);
       }
       if (isSuccessCode(statusCode)) {
-        for (io.swagger.v3.oas.models.media.MediaType mediaType : content.values()) {
-          Schema schema = mediaType.getSchema();
+        for (var mediaType : content.values()) {
+          Optional.ofNullable(response.getExamples()).ifPresent(mediaType::setExample);
+          var schema = mediaType.getSchema();
           if (schema == null) {
             mediaType.setSchema(defaultSchema);
           }
@@ -174,6 +174,11 @@ private void checkRequestBody(ParserContext ctx, OperationExt operation) {
         content.addMediaType(mediaTypeName, mediaType);
         requestBody.setContent(content);
       }
+      if (requestBody.getExamples() != null) {
+        requestBody
+            .getContent()
+            .forEach((key, value) -> value.setExample(requestBody.getExamples()));
+      }
     }
   }
 
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocObjectParser.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocObjectParser.java
@@ -298,14 +298,14 @@ private static Map<String, Object> buildMapFromPairs(List<String> pairs) {
         // Case 3: Simple key-value pairs, possibly nested (e.g., "address.country").
         for (String path : pathsInGroup) {
           String value = pathValues.get(path).get(0);
-          setValue(resultMap, path, parseValue(value));
+          setValue(resultMap, path, parseJson(value));
         }
       }
     }
     return resultMap;
   }
 
-  private static Object parseValue(String value) {
+  public static Object parseJson(String value) {
     try {
       return new UnquotedJsonParser().parse(value);
     } catch (Exception ignored) {
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocTag.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocTag.java
@@ -54,6 +54,46 @@ public class JavaDocTag {
       CUSTOM_TAG.and(it -> it.getText().startsWith("@x-"));
   private static final Predicate<DetailNode> THROWS =
       it -> tree(it).anyMatch(javadocToken(JavadocTokenTypes.THROWS_LITERAL));
+  private static final Predicate<DetailNode> PARAM =
+      it -> tree(it).anyMatch(javadocToken(JavadocTokenTypes.PARAM_LITERAL));
+
+  public static Map<String, String> getParametersDoc(DetailNode node) {
+    var parameters = new LinkedHashMap<String, String>();
+    javaDocTag(
+        node,
+        PARAM,
+        (tag, value) -> {
+          children(tag)
+              .filter(javadocToken(JavadocTokenTypes.PARAMETER_NAME))
+              .findFirst()
+              .map(DetailNode::getText)
+              .ifPresent(
+                  name -> {
+                    children(tag)
+                        .filter(javadocToken(JavadocTokenTypes.DESCRIPTION))
+                        .findFirst()
+                        .map(description -> JavaDocNode.getText(tree(description).toList(), true))
+                        .ifPresent(text -> parameters.put(name, text));
+                  });
+        });
+    return parameters;
+  }
+
+  public static String getReturnDoc(DetailNode node) {
+    var text = new StringBuilder();
+    javaDocTag(
+        node,
+        javadocToken(JavadocTokenTypes.RETURN_LITERAL),
+        (tag, value) -> {
+          children(tag.getParent())
+              .filter(javadocToken(JavadocTokenTypes.DESCRIPTION))
+              .findFirst()
+              .map(description -> JavaDocNode.getText(tree(description).toList(), true))
+              .ifPresent(text::append);
+        });
+    var result = text.toString().trim();
+    return result.isEmpty() ? null : result;
+  }
 
   public static List<SecurityRequirement> securityRequirement(DetailNode node) {
     return parse(node, SECURITY, null).stream()
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/MethodDoc.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/MethodDoc.java
@@ -8,7 +8,6 @@
 import static io.jooby.internal.openapi.javadoc.JavaDocStream.*;
 
 import java.util.*;
-import java.util.stream.Stream;
 
 import com.puppycrawl.tools.checkstyle.api.DetailAST;
 import com.puppycrawl.tools.checkstyle.api.DetailNode;
@@ -19,16 +18,20 @@
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 
 public class MethodDoc extends JavaDocNode {
+  private Map<String, String> parameters;
   private List<SecurityRequirement> securityRequeriments;
   private String operationId;
   private Map<StatusCode, ResponseExt> throwList;
   private List<String> parameterTypes = null;
+  private String returnDoc;
 
   public MethodDoc(JavaDocParser ctx, DetailAST node, DetailAST javadoc) {
     super(ctx, node, javadoc);
     throwList = JavaDocTag.throwList(this.javadoc);
     operationId = JavaDocTag.operationId(this.javadoc);
     securityRequeriments = JavaDocTag.securityRequirement(this.javadoc);
+    parameters = JavaDocTag.getParametersDoc(this.javadoc);
+    returnDoc = JavaDocTag.getReturnDoc(this.javadoc);
   }
 
   MethodDoc(JavaDocParser ctx, DetailAST node, DetailNode javadoc) {
@@ -47,7 +50,7 @@ public void setOperationId(String operationId) {
     this.operationId = operationId;
   }
 
-  public List<SecurityRequirement> getSecurityRequeriments() {
+  public List<SecurityRequirement> getSecurityRequirements() {
     return securityRequeriments;
   }
 
@@ -94,43 +97,52 @@ public List<String> getJavadocParameterNames() {
   }
 
   public String getParameterDoc(String name) {
-    return tree(javadoc)
-        // must be a tag
-        .filter(javadocToken(JavadocTokenTypes.JAVADOC_TAG))
-        .filter(
-            it -> {
-              var children = children(it).toList();
-              return children.stream()
-                      .anyMatch(
-                          t ->
-                              t.getType() == JavadocTokenTypes.PARAM_LITERAL
-                                  && t.getText().equals("@param"))
-                  && children.stream().anyMatch(t -> t.getText().equals(name));
-            })
-        .findFirst()
-        .map(
-            it ->
-                getText(
-                    Stream.of(it.getChildren())
-                        .filter(e -> e.getType() == JavadocTokenTypes.DESCRIPTION)
-                        .flatMap(JavaDocStream::tree)
-                        .toList(),
-                    true))
-        .filter(it -> !it.isEmpty())
-        .orElse(null);
+    var doc = parameters.get(name);
+    return doc == null ? null : doc.replace(exampleCode(doc), "").trim();
+  }
+
+  public Object getParameterExample(String name) {
+    return toExamples(exampleCode(parameters.get(name)));
+  }
+
+  private String exampleCode(String text) {
+    if (text == null) {
+      return "";
+    }
+    var start = text.indexOf("`");
+    if (start == -1) {
+      return "";
+    }
+    var end = text.indexOf("`", start + 1);
+    if (end == -1) {
+      return "";
+    }
+    return text.substring(start, end + 1);
+  }
+
+  private Object toExamples(String text) {
+    var codeExample = exampleCode(text);
+    if (codeExample.isEmpty()) {
+      return null;
+    }
+    var clean = codeExample.substring(1, codeExample.length() - 1);
+    var result = JavaDocObjectParser.parseJson(clean);
+    if (result.equals(codeExample)) {
+      // Like a primitive/basic example
+      return List.of(result);
+    }
+    return result;
   }
 
   public String getReturnDoc() {
-    return tree(javadoc)
-        .filter(javadocToken(JavadocTokenTypes.RETURN_LITERAL))
-        .findFirst()
-        .flatMap(
-            it ->
-                tree(it.getParent())
-                    .filter(javadocToken(JavadocTokenTypes.DESCRIPTION))
-                    .findFirst())
-        .map(it -> getText(tree(it).toList(), true))
-        .orElse(null);
+    if (returnDoc != null) {
+      return returnDoc.replace(exampleCode(returnDoc), "").trim();
+    }
+    return null;
+  }
+
+  public Object getReturnExample() {
+    return toExamples(returnDoc);
   }
 
   public Map<StatusCode, ResponseExt> getThrows() {
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/ApiDocTest.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/ApiDocTest.java
@@ -151,6 +151,9 @@ private void checkResult(OpenAPIResult result) {
             + "          application/json:\n"
             + "            schema:\n"
             + "              $ref: \"#/components/schemas/Book\"\n"
+            + "            example:\n"
+            + "              isbn: X01981\n"
+            + "              title: HarryPotter\n"
             + "        required: true\n"
             + "      responses:\n"
             + "        \"200\":\n"
@@ -159,6 +162,9 @@ private void checkResult(OpenAPIResult result) {
             + "            application/json:\n"
             + "              schema:\n"
             + "                $ref: \"#/components/schemas/Book\"\n"
+            + "              example:\n"
+            + "                id: generatedId\n"
+            + "                isbn: '...'\n"
             + "components:\n"
             + "  schemas:\n"
             + "    Author:\n"
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/LibraryApi.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/LibraryApi.java
@@ -66,8 +66,8 @@ public List<Book> query(@QueryParam BookQuery query) {
    *
    * <p>Book can be created or updated.
    *
-   * @param book Book to create.
-   * @return Saved book.
+   * @param book Book to create. `{isbn: X01981, title: HarryPotter}`
+   * @return Saved book. `{id: generatedId, isbn: ...}`
    * @tag Author
    */
   @POST
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/ScriptLibrary.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/ScriptLibrary.java
@@ -78,8 +78,8 @@ public class ScriptLibrary extends Jooby {
            *
            * <p>Book can be created or updated.
            *
-           * @param book Book to create.
-           * @return Saved book.
+           * @param book Book to create. `{isbn: X01981, title: HarryPotter}`
+           * @return Saved book. `{id: generatedId, isbn: ...}`
            * @tag Author
            * @operationId createBook
            */

Original file line number	Diff line number	Diff line change
`@@ -48,7 +48,7 @@ public static void set(OperationExt operation, MethodDoc doc, List<String> param`
`48`	`48`	`if (!doc.getExtensions().isEmpty()) {`
`49`	`49`	`operation.setExtensions(doc.getExtensions());`
`50`	`50`	`}`
`51`		`- doc.getSecurityRequeriments().forEach(operation::addSecurityItem);`
	`51`	`+ doc.getSecurityRequirements().forEach(operation::addSecurityItem);`
`52`	`52`	`doc.getTags().forEach(operation::addTag);`
`53`	`53`	`// Parameters`
`54`	`54`	`for (var parameterName : parameterNames) {`
`@@ -63,16 +63,19 @@ public static void set(OperationExt operation, MethodDoc doc, List<String> param`
`63`	`63`	`if (paramExt == null) {`
`64`	`64`	`var body = operation.getRequestBody();`
`65`	`65`	`if (body != null) {`
	`66`	`+ body.setExamples(doc.getParameterExample(parameterName));`
`66`	`67`	`body.setDescription(paramDoc);`
`67`	`68`	`}`
`68`	`69`	`} else {`
	`70`	`+ paramExt.setExample(doc.getParameterExample(parameterName));`
`69`	`71`	`paramExt.setDescription(paramDoc);`
`70`	`72`	`}`
`71`	`73`	`}`
`72`	`74`	`}`
`73`	`75`	`// return types`
`74`	`76`	`var defaultResponse = operation.getDefaultResponse();`
`75`	`77`	`if (defaultResponse != null) {`
	`78`	`+ defaultResponse.setExamples(doc.getReturnExample());`
`76`	`79`	`defaultResponse.setDescription(doc.getReturnDoc());`
`77`	`80`	`}`
`78`	`81`	`for (var throwsDoc : doc.getThrows().values()) {`
Original file line number	Diff line number	Diff line change
`@@ -144,14 +144,14 @@ private void checkResponse(`
`144`	`144`	`}`
`145`	`145`
`146`	`146`	`if (content.isEmpty()) {`
`147`		`- io.swagger.v3.oas.models.media.MediaType mediaTypeObject =`
`148`		`- new io.swagger.v3.oas.models.media.MediaType();`
	`147`	`+ var mediaTypeObject = new io.swagger.v3.oas.models.media.MediaType();`
`149`	`148`	`String mediaType = operation.getProduces().stream().findFirst().orElse(MediaType.JSON);`
`150`	`149`	`content.addMediaType(mediaType, mediaTypeObject);`
`151`	`150`	`}`
`152`	`151`	`if (isSuccessCode(statusCode)) {`
`153`		`- for (io.swagger.v3.oas.models.media.MediaType mediaType : content.values()) {`
`154`		`- Schema schema = mediaType.getSchema();`
	`152`	`+ for (var mediaType : content.values()) {`
	`153`	`+ Optional.ofNullable(response.getExamples()).ifPresent(mediaType::setExample);`
	`154`	`+ var schema = mediaType.getSchema();`
`155`	`155`	`if (schema == null) {`
`156`	`156`	`mediaType.setSchema(defaultSchema);`
`157`	`157`	`}`
`@@ -174,6 +174,11 @@ private void checkRequestBody(ParserContext ctx, OperationExt operation) {`
`174`	`174`	`content.addMediaType(mediaTypeName, mediaType);`
`175`	`175`	`requestBody.setContent(content);`
`176`	`176`	`}`
	`177`	`+ if (requestBody.getExamples() != null) {`
	`178`	`+ requestBody`
	`179`	`+ .getContent()`
	`180`	`+ .forEach((key, value) -> value.setExample(requestBody.getExamples()));`
	`181`	`+ }`
`177`	`182`	`}`
`178`	`183`	`}`
`179`	`184`
Original file line number	Diff line number	Diff line change
`@@ -298,14 +298,14 @@ private static Map<String, Object> buildMapFromPairs(List<String> pairs) {`
`298`	`298`	`// Case 3: Simple key-value pairs, possibly nested (e.g., "address.country").`
`299`	`299`	`for (String path : pathsInGroup) {`
`300`	`300`	`String value = pathValues.get(path).get(0);`
`301`		`- setValue(resultMap, path, parseValue(value));`
	`301`	`+ setValue(resultMap, path, parseJson(value));`
`302`	`302`	`}`
`303`	`303`	`}`
`304`	`304`	`}`
`305`	`305`	`return resultMap;`
`306`	`306`	`}`
`307`	`307`
`308`		`- private static Object parseValue(String value) {`
	`308`	`+ public static Object parseJson(String value) {`
`309`	`309`	`try {`
`310`	`310`	`return new UnquotedJsonParser().parse(value);`
`311`	`311`	`} catch (Exception ignored) {`
Original file line number	Diff line number	Diff line change
`@@ -66,8 +66,8 @@ public List<Book> query(@QueryParam BookQuery query) {`
`66`	`66`	`*`
`67`	`67`	`* <p>Book can be created or updated.`
`68`	`68`	`*`
`69`		`- * @param book Book to create.`
`70`		`- * @return Saved book.`
	`69`	+ * @param book Book to create. `{isbn: X01981, title: HarryPotter}`
	`70`	+ * @return Saved book. `{id: generatedId, isbn: ...}`
`71`	`71`	`* @tag Author`
`72`	`72`	`*/`
`73`	`73`	`@POST`
Original file line number	Diff line number	Diff line change
`@@ -78,8 +78,8 @@ public class ScriptLibrary extends Jooby {`
`78`	`78`	`*`
`79`	`79`	`* <p>Book can be created or updated.`
`80`	`80`	`*`
`81`		`- * @param book Book to create.`
`82`		`- * @return Saved book.`
	`81`	+ * @param book Book to create. `{isbn: X01981, title: HarryPotter}`
	`82`	+ * @return Saved book. `{id: generatedId, isbn: ...}`
`83`	`83`	`* @tag Author`
`84`	`84`	`* @operationId createBook`
`85`	`85`	`*/`