[Java][JAXRS-CXF] Improve API documentation in the CXF Server stub an…

…d Client generation (#6708) * Inclusion of API documentation in CXF Server stub generation * Inclusion of API documentation in CXF client generation * Update of the Petstore CXF server sample * Update of the Petstore CXF client sample * Update of the Petstore CXF server annotated base path sample * Update of the Petstore CXF server non spring application sample * Changed {{{appDescription}}} to {{appDescription}} to use the HTML-escaped value in handling special characters like <, > in the description following the correction made by @wing328 * Update of the Petstore CXF samples
swagger-api · Oct 22, 2017 · 7cbd36e · 7cbd36e
1 parent d2eb7cb
commit 7cbd36e
Show file tree

Hide file tree

Showing 63 changed files with 1,247 additions and 2 deletions.
diff --git a/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/api.mustache b/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/api.mustache
@@ -22,6 +22,16 @@ import javax.validation.constraints.*;
 import javax.validation.Valid;
 {{/useBeanValidation}}
 
+{{#appName}}
+/**
+ * {{{appName}}}
+ *
+ {{#appDescription}}
+ * <p>{{{appDescription}}}
+ *
+ {{/appDescription}}
+ */
+{{/appName}}
 @Path("{{^useAnnotatedBasePath}}/{{/useAnnotatedBasePath}}{{#useAnnotatedBasePath}}{{contextPath}}{{/useAnnotatedBasePath}}")
 @Api(value = "/", description = "{{description}}")
 {{#addConsumesProducesJson}}
@@ -32,6 +42,16 @@ public interface {{classname}}  {
 {{#operations}}
 {{#operation}}
 
+    {{#summary}}
+    /**
+     * {{summary}}
+     *
+     {{#notes}}
+     * {{notes}}
+     *
+     {{/notes}}
+     */
+    {{/summary}}
     @{{httpMethod}}
     {{#subresourceOperation}}@Path("{{{path}}}"){{/subresourceOperation}}
 {{#hasConsumes}}

diff --git a/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/apiServiceImpl.mustache b/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/apiServiceImpl.mustache
@@ -25,9 +25,29 @@ import org.springframework.stereotype.Service;
 {{/useSpringAnnotationConfig}}
 {{#description}}
 {{/description}}
+{{#appName}}
+/**
+ * {{{appName}}}
+ *
+ {{#appDescription}}
+ * <p>{{{appDescription}}}
+ {{/appDescription}}
+ *
+ */
+{{/appName}}
 public class {{classname}}ServiceImpl implements {{classname}} {
 {{#operations}}
 {{#operation}}
+    {{#summary}}
+    /**
+     * {{summary}}
+     *
+     {{#notes}}
+     * {{notes}}
+     *
+     {{/notes}}
+     */
+    {{/summary}}
     public {{>returnTypes}} {{nickname}}({{#allParams}}{{>queryParamsImpl}}{{>pathParamsImpl}}{{>headerParamsImpl}}{{>bodyParamsImpl}}{{>formParamsImpl}}{{#hasMore}}, {{/hasMore}}{{/allParams}}) {
         // TODO: Implement...
         

diff --git a/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/api_test.mustache b/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/api_test.mustache
@@ -42,7 +42,15 @@ import org.springframework.test.context.web.WebAppConfiguration;
 
 
 /**
- * API tests for {{classname}}
+ {{#appName}}
+ * {{{appName}}}
+ *
+ {{/appName}}
+ {{#appDescription}}
+ * <p>{{{appDescription}}}
+ *
+ {{/appDescription}}
+ * API tests for {{classname}} 
  */
 {{#generateSpringBootApplication}}
 @RunWith(SpringJUnit4ClassRunner.class)
@@ -91,10 +99,14 @@ public class {{classname}}Test {
 
     {{#operations}}{{#operation}}
     /**
+     {{#summary}}
      * {{summary}}
      *
+     {{#notes}}
      * {{notes}}
      *
+     {{/notes}}
+     {{/summary}}
      * @throws ApiException
      *          if the Api call fails
      */

diff --git a/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/pojo.mustache b/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/pojo.mustache
@@ -17,6 +17,9 @@ import com.fasterxml.jackson.annotation.JsonProperty;
 {{^parent}}@XmlRootElement(name="{{classname}}"){{/parent}}
 {{/withXml}}
 {{#description}}
+/**
+  * {{{description}}}
+ **/
 @ApiModel(description="{{{description}}}")
 {{/description}}
 public class {{classname}} {{#parent}}extends {{{parent}}}{{/parent}} {
@@ -29,6 +32,11 @@ public class {{classname}} {{#parent}}extends {{{parent}}}{{/parent}} {
   @XmlElement(name="{{baseName}}"{{#required}}, required = {{required}}{{/required}})
 {{/withXml}}
   @ApiModelProperty({{#example}}example = "{{{example}}}", {{/example}}{{#required}}required = {{required}}, {{/required}}value = "{{{description}}}")
+{{#description}}
+ /**
+   * {{{description}}}  
+  **/
+{{/description}}
   private {{{datatypeWithEnum}}} {{name}} = {{{defaultValue}}};{{/vars}}
 
   {{#vars}}

diff --git a/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/pom.mustache b/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/pom.mustache
@@ -4,6 +4,9 @@
   <artifactId>{{artifactId}}</artifactId>
   <packaging>jar</packaging>
   <name>{{artifactId}}</name>
+  {{#appDescription}}
+  <description>{{appDescription}}</description>
+  {{/appDescription}}
   <version>{{artifactVersion}}</version>
   <build>
     <sourceDirectory>src/main/java</sourceDirectory>

diff --git a/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/server/pom.mustache b/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/server/pom.mustache
@@ -4,6 +4,9 @@
   <artifactId>{{artifactId}}</artifactId>
   <packaging>war</packaging>
   <name>{{artifactId}}</name>
+  {{#appDescription}}
+  <description>{{appDescription}}</description>
+  {{/appDescription}}
   <version>{{artifactVersion}}</version>
   <build>
     <sourceDirectory>src/main/java</sourceDirectory>

diff --git a/samples/client/petstore/jaxrs-cxf-client/pom.xml b/samples/client/petstore/jaxrs-cxf-client/pom.xml
@@ -4,6 +4,7 @@
   <artifactId>jaxrs-cxf-petstore-client</artifactId>
   <packaging>war</packaging>
   <name>jaxrs-cxf-petstore-client</name>
+  <description>This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key &#x60;special-key&#x60; to test the authorization filters.</description>
   <version>1.0.0</version>
   <build>
     <sourceDirectory>src/main/java</sourceDirectory>

diff --git a/samples/client/petstore/jaxrs-cxf-client/src/gen/java/io/swagger/api/PetApi.java b/samples/client/petstore/jaxrs-cxf-client/src/gen/java/io/swagger/api/PetApi.java
@@ -21,10 +21,22 @@
 import javax.validation.constraints.*;
 import javax.validation.Valid;
 
+/**
+ * Swagger Petstore
+ *
+ * <p>This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.
+ *
+ */
 @Path("/")
 @Api(value = "/", description = "")
 public interface PetApi  {
 
+    /**
+     * Add a new pet to the store
+     *
+     * 
+     *
+     */
     @POST
     @Path("/pet")
     @Consumes({ "application/json", "application/xml" })
@@ -34,6 +46,12 @@ public interface PetApi  {
         @ApiResponse(code = 405, message = "Invalid input") })
     public void addPet(@Valid Pet body);
 
+    /**
+     * Deletes a pet
+     *
+     * 
+     *
+     */
     @DELETE
     @Path("/pet/{petId}")
     @Produces({ "application/xml", "application/json" })
@@ -42,6 +60,12 @@ public interface PetApi  {
         @ApiResponse(code = 400, message = "Invalid pet value") })
     public void deletePet(@PathParam("petId") Long petId, @HeaderParam("api_key") String apiKey);
 
+    /**
+     * Finds Pets by status
+     *
+     * Multiple status values can be provided with comma separated strings
+     *
+     */
     @GET
     @Path("/pet/findByStatus")
     @Produces({ "application/xml", "application/json" })
@@ -51,6 +75,12 @@ public interface PetApi  {
         @ApiResponse(code = 400, message = "Invalid status value") })
     public List<Pet> findPetsByStatus(@QueryParam("status") @NotNull List<String> status);
 
+    /**
+     * Finds Pets by tags
+     *
+     * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
+     *
+     */
     @GET
     @Path("/pet/findByTags")
     @Produces({ "application/xml", "application/json" })
@@ -60,6 +90,12 @@ public interface PetApi  {
         @ApiResponse(code = 400, message = "Invalid tag value") })
     public List<Pet> findPetsByTags(@QueryParam("tags") @NotNull List<String> tags);
 
+    /**
+     * Find pet by ID
+     *
+     * Returns a single pet
+     *
+     */
     @GET
     @Path("/pet/{petId}")
     @Produces({ "application/xml", "application/json" })
@@ -70,6 +106,12 @@ public interface PetApi  {
         @ApiResponse(code = 404, message = "Pet not found") })
     public Pet getPetById(@PathParam("petId") Long petId);
 
+    /**
+     * Update an existing pet
+     *
+     * 
+     *
+     */
     @PUT
     @Path("/pet")
     @Consumes({ "application/json", "application/xml" })
@@ -81,6 +123,12 @@ public interface PetApi  {
         @ApiResponse(code = 405, message = "Validation exception") })
     public void updatePet(@Valid Pet body);
 
+    /**
+     * Updates a pet in the store with form data
+     *
+     * 
+     *
+     */
     @POST
     @Path("/pet/{petId}")
     @Consumes({ "application/x-www-form-urlencoded" })
@@ -90,6 +138,12 @@ public interface PetApi  {
         @ApiResponse(code = 405, message = "Invalid input") })
     public void updatePetWithForm(@PathParam("petId") Long petId, @Multipart(value = "name", required = false)  String name, @Multipart(value = "status", required = false)  String status);
 
+    /**
+     * uploads an image
+     *
+     * 
+     *
+     */
     @POST
     @Path("/pet/{petId}/uploadImage")
     @Consumes({ "multipart/form-data" })

diff --git a/samples/client/petstore/jaxrs-cxf-client/src/gen/java/io/swagger/api/StoreApi.java b/samples/client/petstore/jaxrs-cxf-client/src/gen/java/io/swagger/api/StoreApi.java
@@ -20,10 +20,22 @@
 import javax.validation.constraints.*;
 import javax.validation.Valid;
 
+/**
+ * Swagger Petstore
+ *
+ * <p>This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.
+ *
+ */
 @Path("/")
 @Api(value = "/", description = "")
 public interface StoreApi  {
 
+    /**
+     * Delete purchase order by ID
+     *
+     * For valid response try integer IDs with value &lt; 1000. Anything above 1000 or nonintegers will generate API errors
+     *
+     */
     @DELETE
     @Path("/store/order/{orderId}")
     @Produces({ "application/xml", "application/json" })
@@ -33,6 +45,12 @@ public interface StoreApi  {
         @ApiResponse(code = 404, message = "Order not found") })
     public void deleteOrder(@PathParam("orderId") String orderId);
 
+    /**
+     * Returns pet inventories by status
+     *
+     * Returns a map of status codes to quantities
+     *
+     */
     @GET
     @Path("/store/inventory")
     @Produces({ "application/json" })
@@ -41,6 +59,12 @@ public interface StoreApi  {
         @ApiResponse(code = 200, message = "successful operation", response = Map.class, responseContainer = "Map") })
     public Map<String, Integer> getInventory();
 
+    /**
+     * Find purchase order by ID
+     *
+     * For valid response try integer IDs with value &lt;&#x3D; 5 or &gt; 10. Other values will generated exceptions
+     *
+     */
     @GET
     @Path("/store/order/{orderId}")
     @Produces({ "application/xml", "application/json" })
@@ -51,6 +75,12 @@ public interface StoreApi  {
         @ApiResponse(code = 404, message = "Order not found") })
     public Order getOrderById(@PathParam("orderId") @Min(1) @Max(5) Long orderId);
 
+    /**
+     * Place an order for a pet
+     *
+     * 
+     *
+     */
     @POST
     @Path("/store/order")
     @Produces({ "application/xml", "application/json" })