Updated documentation

2015-02-16 13:51:42 +01:00
parent cd4ef60cc3
commit efea76d243
9 changed files with 129 additions and 119 deletions
--- a/README.adoc
+++ b/README.adoc
@@ -128,6 +128,9 @@ image::images/asciidoc_html.PNG[asciidoc_html]
 === Generated HTML via Mkdocs
 image::images/mkdocs_html.PNG[mkdocs_html]

+=== Generated PDF via AsciidoctorJ
+image::images/asciidoc_pdf.PNG[asciidoc_pdf]
+
 == Document Builder
 The converter allows to build an AsciiDoc or Markdown document via the Builder pattern:
 [source,java]
--- a/build.gradle
+++ b/build.gradle
@@ -8,11 +8,7 @@ buildscript {
        classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.6'
        classpath 'io.spring.gradle:dependency-management-plugin:0.3.1.RELEASE'
        classpath 'org.kt3k.gradle.plugin:coveralls-gradle-plugin:2.0.1'
-        classpath 'me.champeau.gradle:jbake-gradle-plugin:0.2'
-        classpath 'org.jbake:jbake-core:2.3.2'
        classpath 'org.asciidoctor:asciidoctorj:1.5.2'
-        classpath 'org.freemarker:freemarker:2.3.19'
-        classpath 'org.springframework.boot:spring-boot-gradle-plugin:1.2.1.RELEASE'
        classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.0'
    }
 }
@@ -59,10 +55,12 @@ dependencyManagement {
 }

 asciidoctor {
+    backends = ['html5', 'pdf']
    attributes = [
            doctype: 'book',
            toc: 'left',
-            toclevels: '1'
+            toclevels: '2',
+            numbered: ''
    ]
 }

@@ -77,6 +75,10 @@ tasks.coveralls {
    dependsOn 'check'
 }

+tasks.asciidoctor {
+    dependsOn 'check'
+}
+
 task wrapper(type: Wrapper) {
    gradleVersion = '2.2.1'
 }
--- a/images/asciidoc.PNG
+++ b/images/asciidoc.PNG
--- a/images/asciidoc_html.PNG
+++ b/images/asciidoc_html.PNG
--- a/images/asciidoc_pdf.PNG
+++ b/images/asciidoc_pdf.PNG
--- a/images/markdown.PNG
+++ b/images/markdown.PNG
--- a/src/docs/asciidoc/swagger.adoc
+++ b/src/docs/asciidoc/swagger.adoc
@@ -7,19 +7,20 @@ For this sample, you can use the api key `special-key` to test the authorization

 Version: 1.0.0

-== Update an existing pet
+== Features
+=== Update an existing pet
 ----
 PUT /pets
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 body,body,Pet object that needs to be added to the store,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -28,58 +29,58 @@ Code,Description
 405,Validation exception
 |===

-=== Consumes
+==== Consumes
 * application/json
 * application/xml

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Add a new pet to the store
+=== Add a new pet to the store
 ----
 POST /pets
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 body,body,Pet object that needs to be added to the store,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 405,Invalid input
 |===

-=== Consumes
+==== Consumes
 * application/json
 * application/xml

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Finds Pets by status
+=== Finds Pets by status
 ----
 GET /pets/findByStatus
 ----

-=== Description
+==== Description
 :hardbreaks:
 Multiple status values can be provided with comma seperated strings

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 status,query,Status values that need to be considered for filter,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -87,27 +88,27 @@ Code,Description
 400,Invalid status value
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Finds Pets by tags
+=== Finds Pets by tags
 ----
 GET /pets/findByTags
 ----

-=== Description
+==== Description
 :hardbreaks:
 Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 tags,query,Tags to filter by,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -115,27 +116,27 @@ Code,Description
 400,Invalid tag value
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Find pet by ID
+=== Find pet by ID
 ----
 GET /pets/{petId}
 ----

-=== Description
+==== Description
 :hardbreaks:
 Returns a pet when ID < 10.  ID > 10 or nonintegers will simulate API error conditions

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 petId,path,ID of pet that needs to be fetched,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -144,16 +145,16 @@ Code,Description
 404,Pet not found
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Deletes a pet
+=== Deletes a pet
 ----
 DELETE /pets/{petId}
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
@@ -161,23 +162,23 @@ api_key,header,,true
 petId,path,Pet id to delete,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 400,Invalid pet value
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Updates a pet in the store with form data
+=== Updates a pet in the store with form data
 ----
 POST /pets/{petId}
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
@@ -186,33 +187,33 @@ name,formData,Updated name of the pet,true
 status,formData,Updated status of the pet,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 405,Invalid input
 |===

-=== Consumes
+==== Consumes
 * application/x-www-form-urlencoded

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Place an order for a pet
+=== Place an order for a pet
 ----
 POST /stores/order
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 body,body,order placed for purchasing the pet,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -220,27 +221,27 @@ Code,Description
 400,Invalid Order
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Find purchase order by ID
+=== Find purchase order by ID
 ----
 GET /stores/order/{orderId}
 ----

-=== Description
+==== Description
 :hardbreaks:
 For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 orderId,path,ID of pet that needs to be fetched,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -249,27 +250,27 @@ Code,Description
 404,Order not found
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Delete purchase order by ID
+=== Delete purchase order by ID
 ----
 DELETE /stores/order/{orderId}
 ----

-=== Description
+==== Description
 :hardbreaks:
 For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 orderId,path,ID of the order that needs to be deleted,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -277,89 +278,89 @@ Code,Description
 404,Order not found
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Create user
+=== Create user
 ----
 POST /users
 ----

-=== Description
+==== Description
 :hardbreaks:
 This can only be done by the logged in user.

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 body,body,Created user object,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 default,successful operation
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Creates list of users with given input array
+=== Creates list of users with given input array
 ----
 POST /users/createWithArray
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 body,body,List of user object,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 default,successful operation
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Creates list of users with given input array
+=== Creates list of users with given input array
 ----
 POST /users/createWithList
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 body,body,List of user object,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 default,successful operation
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Logs user into the system
+=== Logs user into the system
 ----
 GET /users/login
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
@@ -367,7 +368,7 @@ username,query,The user name for login,false
 password,query,The password for login in clear text,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -375,39 +376,39 @@ Code,Description
 400,Invalid username/password supplied
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Logs out current logged in user session
+=== Logs out current logged in user session
 ----
 GET /users/logout
 ----

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
 default,successful operation
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Get user by user name
+=== Get user by user name
 ----
 GET /users/{username}
 ----

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 username,path,The name that needs to be fetched. Use user1 for testing.,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -416,20 +417,20 @@ Code,Description
 404,User not found
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Updated user
+=== Updated user
 ----
 PUT /users/{username}
 ----

-=== Description
+==== Description
 :hardbreaks:
 This can only be done by the logged in user.

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
@@ -437,7 +438,7 @@ username,path,name that need to be deleted,true
 body,body,Updated user object,false
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -445,27 +446,27 @@ Code,Description
 404,User not found
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

-== Delete user
+=== Delete user
 ----
 DELETE /users/{username}
 ----

-=== Description
+==== Description
 :hardbreaks:
 This can only be done by the logged in user.

-=== Parameters
+==== Parameters
 [format="csv", options="header"]
 |===
 Name,Located in,Description,Required
 username,path,The name that needs to be deleted,true
 |===

-=== Responses
+==== Responses
 [format="csv", options="header"]
 |===
 Code,Description
@@ -473,7 +474,7 @@ Code,Description
 404,User not found
 |===

-=== Produces
+==== Produces
 * application/json
 * application/xml

--- a/src/docs/markdown/swagger.md
+++ b/src/docs/markdown/swagger.md
@@ -7,7 +7,8 @@ For this sample, you can use the api key `special-key` to test the authorization

 Version: 1.0.0

-## Update an existing pet
+## Features
+### Update an existing pet
 ```
 PUT /pets
 ```
@@ -34,7 +35,7 @@ PUT /pets
 * application/json
 * application/xml

-## Add a new pet to the store
+### Add a new pet to the store
 ```
 POST /pets
 ```
@@ -59,7 +60,7 @@ POST /pets
 * application/json
 * application/xml

-## Finds Pets by status
+### Finds Pets by status
 ```
 GET /pets/findByStatus
 ```
@@ -85,7 +86,7 @@ Multiple status values can be provided with comma seperated strings
 * application/json
 * application/xml

-## Finds Pets by tags
+### Finds Pets by tags
 ```
 GET /pets/findByTags
 ```
@@ -111,7 +112,7 @@ Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3
 * application/json
 * application/xml

-## Find pet by ID
+### Find pet by ID
 ```
 GET /pets/{petId}
 ```
@@ -138,7 +139,7 @@ Returns a pet when ID < 10.  ID > 10 or nonintegers will simulate API error cond
 * application/json
 * application/xml

-## Deletes a pet
+### Deletes a pet
 ```
 DELETE /pets/{petId}
 ```
@@ -160,7 +161,7 @@ DELETE /pets/{petId}
 * application/json
 * application/xml

-## Updates a pet in the store with form data
+### Updates a pet in the store with form data
 ```
 POST /pets/{petId}
 ```
@@ -186,7 +187,7 @@ POST /pets/{petId}
 * application/json
 * application/xml

-## Place an order for a pet
+### Place an order for a pet
 ```
 POST /stores/order
 ```
@@ -208,7 +209,7 @@ POST /stores/order
 * application/json
 * application/xml

-## Find purchase order by ID
+### Find purchase order by ID
 ```
 GET /stores/order/{orderId}
 ```
@@ -235,7 +236,7 @@ For valid response try integer IDs with value <= 5 or > 10. Other values will ge
 * application/json
 * application/xml

-## Delete purchase order by ID
+### Delete purchase order by ID
 ```
 DELETE /stores/order/{orderId}
 ```
@@ -261,7 +262,7 @@ For valid response try integer IDs with value < 1000. Anything above 1000 or non
 * application/json
 * application/xml

-## Create user
+### Create user
 ```
 POST /users
 ```
@@ -286,7 +287,7 @@ This can only be done by the logged in user.
 * application/json
 * application/xml

-## Creates list of users with given input array
+### Creates list of users with given input array
 ```
 POST /users/createWithArray
 ```
@@ -307,7 +308,7 @@ POST /users/createWithArray
 * application/json
 * application/xml

-## Creates list of users with given input array
+### Creates list of users with given input array
 ```
 POST /users/createWithList
 ```
@@ -328,7 +329,7 @@ POST /users/createWithList
 * application/json
 * application/xml

-## Logs user into the system
+### Logs user into the system
 ```
 GET /users/login
 ```
@@ -351,7 +352,7 @@ GET /users/login
 * application/json
 * application/xml

-## Logs out current logged in user session
+### Logs out current logged in user session
 ```
 GET /users/logout
 ```
@@ -366,7 +367,7 @@ GET /users/logout
 * application/json
 * application/xml

-## Get user by user name
+### Get user by user name
 ```
 GET /users/{username}
 ```
@@ -389,7 +390,7 @@ GET /users/{username}
 * application/json
 * application/xml

-## Updated user
+### Updated user
 ```
 PUT /users/{username}
 ```
@@ -416,7 +417,7 @@ This can only be done by the logged in user.
 * application/json
 * application/xml

-## Delete user
+### Delete user
 ```
 DELETE /users/{username}
 ```
--- a/src/main/java/io/swagger2markup/Swagger2MarkupConverter.java
+++ b/src/main/java/io/swagger2markup/Swagger2MarkupConverter.java
@@ -29,7 +29,7 @@ import java.util.Map;
 public class Swagger2MarkupConverter {
    private static final Logger logger = LoggerFactory.getLogger(Swagger2MarkupConverter.class);
    private static final String VERSION = "Version: ";
-    private static final String SUMMARY = "Summary";
+    private static final String FEATURES = "Features";
    private static final String DESCRIPTION = "Description";
    private static final String PARAMETERS = "Parameters";
    private static final String PRODUCES = "Produces";
@@ -77,13 +77,16 @@ public class Swagger2MarkupConverter {
    }

    private void paths(Map<String, Path> paths) {
-        for(Map.Entry<String, Path> entry : paths.entrySet()){
-            Path path = entry.getValue();
-            path("GET", entry.getKey(), path.getGet());
-            path("PUT", entry.getKey(), path.getPut());
-            path("DELETE", entry.getKey(), path.getDelete());
-            path("POST", entry.getKey(), path.getPost());
-            path("PATCH", entry.getKey(), path.getPatch());
+        if(MapUtils.isNotEmpty(paths)) {
+            documentBuilder.sectionTitleLevel1(FEATURES);
+            for (Map.Entry<String, Path> entry : paths.entrySet()) {
+                Path path = entry.getValue();
+                path("GET", entry.getKey(), path.getGet());
+                path("PUT", entry.getKey(), path.getPut());
+                path("DELETE", entry.getKey(), path.getDelete());
+                path("POST", entry.getKey(), path.getPost());
+                path("PATCH", entry.getKey(), path.getPatch());
+            }
        }
    }

@@ -109,7 +112,7 @@ public class Swagger2MarkupConverter {
    private void pathTitle(String httpMethod, String resourcePath, Operation operation) {
        String summary = operation.getSummary();
        if(StringUtils.isNotBlank(summary)) {
-            documentBuilder.sectionTitleLevel1(operation.getSummary());
+            documentBuilder.sectionTitleLevel2(operation.getSummary());
            documentBuilder.listing(httpMethod + " " + resourcePath);
        }else{
            documentBuilder.sectionTitleLevel1(httpMethod + " " + resourcePath);
@@ -119,7 +122,7 @@ public class Swagger2MarkupConverter {
    private void descriptionSection(Operation operation) {
        String description = operation.getDescription();
        if(StringUtils.isNotBlank(description)){
-            documentBuilder.sectionTitleLevel2(DESCRIPTION);
+            documentBuilder.sectionTitleLevel3(DESCRIPTION);
            documentBuilder.paragraph(description);
        }
    }
@@ -127,7 +130,7 @@ public class Swagger2MarkupConverter {
    private void consumesSection(Operation operation) {
        List<String> consumes = operation.getConsumes();
        if(CollectionUtils.isNotEmpty(consumes)){
-            documentBuilder.sectionTitleLevel2(CONSUMES);
+            documentBuilder.sectionTitleLevel3(CONSUMES);
            documentBuilder.unorderedList(consumes);
        }

@@ -136,7 +139,7 @@ public class Swagger2MarkupConverter {
    private void producesSection(Operation operation) {
        List<String> produces = operation.getProduces();
        if(CollectionUtils.isNotEmpty(produces)){
-            documentBuilder.sectionTitleLevel2(PRODUCES);
+            documentBuilder.sectionTitleLevel3(PRODUCES);
            documentBuilder.unorderedList(produces);
        }
    }
@@ -154,7 +157,7 @@ public class Swagger2MarkupConverter {
                        append(parameter.getRequired());
                csvContent.add(rowBuilder.toString());
            }
-            documentBuilder.sectionTitleLevel2(PARAMETERS);
+            documentBuilder.sectionTitleLevel3(PARAMETERS);
            documentBuilder.tableWithHeaderRow(csvContent);
        }
    }
@@ -171,7 +174,7 @@ public class Swagger2MarkupConverter {
                        append(response.getDescription());
                csvContent.add(rowBuilder.toString());
            }
-            documentBuilder.sectionTitleLevel2(RESPONSES);
+            documentBuilder.sectionTitleLevel3(RESPONSES);
            documentBuilder.tableWithHeaderRow(csvContent);
        }
    }