Add JavaDoc to api and apiInterface templates for the JavaJaxRS spec …

…generator (#17705) * Add javadoc to api and apiInterface templates for JavaJaxRS/spec. * Updated samples with javadoc change.
OpenAPITools · Jan 27, 2024 · 0a0428b · 0a0428b
1 parent d152f4d
commit 0a0428b
Show file tree

Hide file tree

Showing 27 changed files with 649 additions and 1 deletion.
diff --git a/modules/openapi-generator/src/main/resources/JavaJaxRS/spec/api.mustache b/modules/openapi-generator/src/main/resources/JavaJaxRS/spec/api.mustache
@@ -20,6 +20,9 @@ import java.util.List;
 {{#useBeanValidation}}import {{javaxPackage}}.validation.constraints.*;
 import {{javaxPackage}}.validation.Valid;{{/useBeanValidation}}
 
+/**
+* Represents a collection of functions to interact with the API endpoints.
+*/
 @Path("{{commonPath}}"){{#useSwaggerAnnotations}}
 @Api(description = "the {{{baseName}}} API"){{/useSwaggerAnnotations}}{{#hasConsumes}}
 @Consumes({ {{#consumes}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/consumes}} }){{/hasConsumes}}{{#hasProduces}}
@@ -32,4 +35,4 @@ public {{#interfaceOnly}}interface{{/interfaceOnly}}{{^interfaceOnly}}class{{/in
 {{#interfaceOnly}}{{>apiInterface}}{{/interfaceOnly}}{{^interfaceOnly}}{{>apiMethod}}{{/interfaceOnly}}
 {{/operation}}
 }
-{{/operations}}
+{{/operations}}
diff --git a/modules/openapi-generator/src/main/resources/JavaJaxRS/spec/apiInterface.mustache b/modules/openapi-generator/src/main/resources/JavaJaxRS/spec/apiInterface.mustache
@@ -1,3 +1,13 @@
+    /**
+     * {{{notes}}}
+     *
+     {{#allParams}}
+     * @param {{paramName}} {{description}}
+     {{/allParams}}
+     {{#responses}}
+     * @return {{{message}}}
+     {{/responses}}
+     */
     @{{httpMethod}}{{#subresourceOperation}}
     @Path("{{{path}}}"){{/subresourceOperation}}{{#hasConsumes}}
     @Consumes({ {{#consumes}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/consumes}} }){{/hasConsumes}}{{#hasProduces}}

diff --git a/...store/jaxrs-spec-interface-response/src/gen/java/org/openapitools/api/AnotherFakeApi.java b/...store/jaxrs-spec-interface-response/src/gen/java/org/openapitools/api/AnotherFakeApi.java
@@ -14,11 +14,21 @@
 import javax.validation.constraints.*;
 import javax.validation.Valid;
 
+/**
+* Represents a collection of functions to interact with the API endpoints.
+*/
 @Path("/another-fake/dummy")
 @Api(description = "the another-fake API")
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen")
 public interface AnotherFakeApi {
 
+    /**
+     * To test special tags and operation ID starting with number
+     *
+     * @param uuidTest to test uuid example value
+     * @param body client model
+     * @return successful operation
+     */
     @PATCH
     @Consumes({ "application/json" })
     @Produces({ "application/json" })

diff --git a/...ver/petstore/jaxrs-spec-interface-response/src/gen/java/org/openapitools/api/FakeApi.java b/...ver/petstore/jaxrs-spec-interface-response/src/gen/java/org/openapitools/api/FakeApi.java
@@ -23,11 +23,20 @@
 import javax.validation.constraints.*;
 import javax.validation.Valid;
 
+/**
+* Represents a collection of functions to interact with the API endpoints.
+*/
 @Path("/fake")
 @Api(description = "the fake API")
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen")
 public interface FakeApi {
 
+    /**
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body
+     * @return successful operation
+     */
     @POST
     @Path("/create_xml_item")
     @Consumes({ "application/xml", "application/xml; charset=utf-8", "application/xml; charset=utf-16", "text/xml", "text/xml; charset=utf-8", "text/xml; charset=utf-16" })
@@ -37,6 +46,12 @@ public interface FakeApi {
     Response createXmlItem(@Valid @NotNull XmlItem xmlItem);
 
 
+    /**
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body
+     * @return Output boolean
+     */
     @POST
     @Path("/outer/boolean")
     @Produces({ "*/*" })
@@ -46,6 +61,12 @@ public interface FakeApi {
     Response fakeOuterBooleanSerialize(@Valid Boolean body);
 
 
+    /**
+     * Test serialization of object with outer number type
+     *
+     * @param body Input composite as post body
+     * @return Output composite
+     */
     @POST
     @Path("/outer/composite")
     @Produces({ "*/*" })
@@ -55,6 +76,12 @@ public interface FakeApi {
     Response fakeOuterCompositeSerialize(@Valid OuterComposite body);
 
 
+    /**
+     * Test serialization of outer number types
+     *
+     * @param body Input number as post body
+     * @return Output number
+     */
     @POST
     @Path("/outer/number")
     @Produces({ "*/*" })
@@ -64,6 +91,12 @@ public interface FakeApi {
     Response fakeOuterNumberSerialize(@Valid BigDecimal body);
 
 
+    /**
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body
+     * @return Output string
+     */
     @POST
     @Path("/outer/string")
     @Produces({ "*/*" })
@@ -73,6 +106,12 @@ public interface FakeApi {
     Response fakeOuterStringSerialize(@Valid String body);
 
 
+    /**
+     * For this test, the body for this request much reference a schema named `File`.
+     *
+     * @param body 
+     * @return Success
+     */
     @PUT
     @Path("/body-with-file-schema")
     @Consumes({ "application/json" })
@@ -82,6 +121,13 @@ public interface FakeApi {
     Response testBodyWithFileSchema(@Valid @NotNull FileSchemaTestClass body);
 
 
+    /**
+     * 
+     *
+     * @param query 
+     * @param body 
+     * @return Success
+     */
     @PUT
     @Path("/body-with-query-params")
     @Consumes({ "application/json" })
@@ -91,6 +137,12 @@ public interface FakeApi {
     Response testBodyWithQueryParams(@QueryParam("query") @NotNull   String query,@Valid @NotNull User body);
 
 
+    /**
+     * To test \"client\" model
+     *
+     * @param body client model
+     * @return successful operation
+     */
     @PATCH
     @Consumes({ "application/json" })
     @Produces({ "application/json" })
@@ -100,6 +152,26 @@ public interface FakeApi {
     Response testClientModel(@Valid @NotNull Client body);
 
 
+    /**
+     * Fake endpoint for testing various parameters  假端點  偽のエンドポイント  가짜 엔드 포인트
+     *
+     * @param number None
+     * @param _double None
+     * @param patternWithoutDelimiter None
+     * @param _byte None
+     * @param integer None
+     * @param int32 None
+     * @param int64 None
+     * @param _float None
+     * @param string None
+     * @param binary None
+     * @param date None
+     * @param dateTime None
+     * @param password None
+     * @param paramCallback None
+     * @return Invalid username supplied
+     * @return User not found
+     */
     @POST
     @Consumes({ "application/x-www-form-urlencoded" })
     @ApiOperation(value = "Fake endpoint for testing various parameters  假端點  偽のエンドポイント  가짜 엔드 포인트", notes = "Fake endpoint for testing various parameters  假端點  偽のエンドポイント  가짜 엔드 포인트", authorizations = {
@@ -112,6 +184,20 @@ public interface FakeApi {
     Response testEndpointParameters(@FormParam(value = "number")  BigDecimal number,@FormParam(value = "double")  Double _double,@FormParam(value = "pattern_without_delimiter")  String patternWithoutDelimiter,@FormParam(value = "byte")  byte[] _byte,@FormParam(value = "integer")  Integer integer,@FormParam(value = "int32")  Integer int32,@FormParam(value = "int64")  Long int64,@FormParam(value = "float")  Float _float,@FormParam(value = "string")  String string, @FormParam(value = "binary") InputStream binaryInputStream,@FormParam(value = "date")  LocalDate date,@FormParam(value = "dateTime")  Date dateTime,@FormParam(value = "password")  String password,@FormParam(value = "callback")  String paramCallback);
 
 
+    /**
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array)
+     * @param enumHeaderString Header parameter enum test (string)
+     * @param enumQueryStringArray Query parameter enum test (string array)
+     * @param enumQueryString Query parameter enum test (string)
+     * @param enumQueryInteger Query parameter enum test (double)
+     * @param enumQueryDouble Query parameter enum test (double)
+     * @param enumFormStringArray Form parameter enum test (string array)
+     * @param enumFormString Form parameter enum test (string)
+     * @return Invalid request
+     * @return Not found
+     */
     @GET
     @Consumes({ "application/x-www-form-urlencoded" })
     @ApiOperation(value = "To test enum parameters", notes = "To test enum parameters", tags={ "fake" })
@@ -121,13 +207,30 @@ public interface FakeApi {
     Response testEnumParameters(@HeaderParam("enum_header_string_array")   @ApiParam("Header parameter enum test (string array)") List<String> enumHeaderStringArray,@HeaderParam("enum_header_string")  @DefaultValue("-efg")  @ApiParam("Header parameter enum test (string)") String enumHeaderString,@QueryParam("enum_query_string_array")  @ApiParam("Query parameter enum test (string array)")  List<String> enumQueryStringArray,@QueryParam("enum_query_string") @DefaultValue("-efg")  @ApiParam("Query parameter enum test (string)")  String enumQueryString,@QueryParam("enum_query_integer")  @ApiParam("Query parameter enum test (double)")  Integer enumQueryInteger,@QueryParam("enum_query_double")  @ApiParam("Query parameter enum test (double)")  Double enumQueryDouble,@FormParam(value = "enum_form_string_array")  List<String> enumFormStringArray,@FormParam(value = "enum_form_string")  String enumFormString);
 
 
+    /**
+     * Fake endpoint to test group parameters (optional)
+     *
+     * @param requiredStringGroup Required String in group parameters
+     * @param requiredBooleanGroup Required Boolean in group parameters
+     * @param requiredInt64Group Required Integer in group parameters
+     * @param stringGroup String in group parameters
+     * @param booleanGroup Boolean in group parameters
+     * @param int64Group Integer in group parameters
+     * @return Something wrong
+     */
     @DELETE
     @ApiOperation(value = "Fake endpoint to test group parameters (optional)", notes = "Fake endpoint to test group parameters (optional)", tags={ "fake" })
     @ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Something wrong", response = Void.class) })
     Response testGroupParameters(@QueryParam("required_string_group") @NotNull  @ApiParam("Required String in group parameters")  Integer requiredStringGroup,@HeaderParam("required_boolean_group") @NotNull   @ApiParam("Required Boolean in group parameters") Boolean requiredBooleanGroup,@QueryParam("required_int64_group") @NotNull  @ApiParam("Required Integer in group parameters")  Long requiredInt64Group,@QueryParam("string_group")  @ApiParam("String in group parameters")  Integer stringGroup,@HeaderParam("boolean_group")   @ApiParam("Boolean in group parameters") Boolean booleanGroup,@QueryParam("int64_group")  @ApiParam("Integer in group parameters")  Long int64Group);
 
 
+    /**
+     * 
+     *
+     * @param param request body
+     * @return successful operation
+     */
     @POST
     @Path("/inline-additionalProperties")
     @Consumes({ "application/json" })
@@ -137,6 +240,13 @@ public interface FakeApi {
     Response testInlineAdditionalProperties(@Valid @NotNull Map<String, String> param);
 
 
+    /**
+     * 
+     *
+     * @param param field1
+     * @param param2 field2
+     * @return successful operation
+     */
     @GET
     @Path("/jsonFormData")
     @Consumes({ "application/x-www-form-urlencoded" })
@@ -146,6 +256,16 @@ public interface FakeApi {
     Response testJsonFormData(@FormParam(value = "param")  String param,@FormParam(value = "param2")  String param2);
 
 
+    /**
+     * To test the collection format in query parameters
+     *
+     * @param pipe 
+     * @param ioutil 
+     * @param http 
+     * @param url 
+     * @param context 
+     * @return Success
+     */
     @PUT
     @Path("/test-query-parameters")
     @ApiOperation(value = "", notes = "To test the collection format in query parameters", tags={ "fake" })
@@ -154,6 +274,14 @@ public interface FakeApi {
     Response testQueryParameterCollectionFormat(@QueryParam("pipe") @NotNull   List<String> pipe,@QueryParam("ioutil") @NotNull   List<String> ioutil,@QueryParam("http") @NotNull   List<String> http,@QueryParam("url") @NotNull   List<String> url,@QueryParam("context") @NotNull   List<String> context);
 
 
+    /**
+     * 
+     *
+     * @param petId ID of pet to update
+     * @param requiredFile file to upload
+     * @param additionalMetadata Additional data to pass to server
+     * @return successful operation
+     */
     @POST
     @Path("/{petId}/uploadImageWithRequiredFile")
     @Consumes({ "multipart/form-data" })

diff --git a/...jaxrs-spec-interface-response/src/gen/java/org/openapitools/api/FakeClassnameTestApi.java b/...jaxrs-spec-interface-response/src/gen/java/org/openapitools/api/FakeClassnameTestApi.java
@@ -13,11 +13,20 @@
 import javax.validation.constraints.*;
 import javax.validation.Valid;
 
+/**
+* Represents a collection of functions to interact with the API endpoints.
+*/
 @Path("/fake_classname_test")
 @Api(description = "the fake_classname_test API")
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen")
 public interface FakeClassnameTestApi {
 
+    /**
+     * To test class name in snake case
+     *
+     * @param body client model
+     * @return successful operation
+     */
     @PATCH
     @Consumes({ "application/json" })
     @Produces({ "application/json" })