diff --git a/README.adoc b/README.adoc index ce6fd605..986d8578 100644 --- 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] diff --git a/build.gradle b/build.gradle index f09b2d38..6ead77c9 100644 --- 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' } \ No newline at end of file diff --git a/images/asciidoc.PNG b/images/asciidoc.PNG index a64faac4..3541d1a2 100644 Binary files a/images/asciidoc.PNG and b/images/asciidoc.PNG differ diff --git a/images/asciidoc_html.PNG b/images/asciidoc_html.PNG index 46962bb6..87bb9566 100644 Binary files a/images/asciidoc_html.PNG and b/images/asciidoc_html.PNG differ diff --git a/images/asciidoc_pdf.PNG b/images/asciidoc_pdf.PNG new file mode 100644 index 00000000..15a369f3 Binary files /dev/null and b/images/asciidoc_pdf.PNG differ diff --git a/images/markdown.PNG b/images/markdown.PNG index b1d726ef..38e883ba 100644 Binary files a/images/markdown.PNG and b/images/markdown.PNG differ diff --git a/src/docs/asciidoc/swagger.adoc b/src/docs/asciidoc/swagger.adoc index 0f8b2b64..aa36b7c0 100644 --- 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 diff --git a/src/docs/markdown/swagger.md b/src/docs/markdown/swagger.md index 7e7ebe49..6d71b30c 100644 --- 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} ``` diff --git a/src/main/java/io/swagger2markup/Swagger2MarkupConverter.java b/src/main/java/io/swagger2markup/Swagger2MarkupConverter.java index 17e7865e..d80acd18 100644 --- 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 paths) { - for(Map.Entry 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 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 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 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); } }