diff --git a/src/docs/asciidoc/command_line_interface.adoc b/src/docs/asciidoc/command_line_interface.adoc index 7568138d..c8b4ead7 100644 --- a/src/docs/asciidoc/command_line_interface.adoc +++ b/src/docs/asciidoc/command_line_interface.adoc @@ -26,22 +26,28 @@ NAME Markup documents. SYNOPSIS - swagger2markup convert [(-c | --configFile )] - [(-h | --help)] (-i | --inputFile ) - (-o | --outputPath ) + swagger2markup convert [(-c | --config )] + [(-d | --outputDir )] + [(-f | --outputFile )] + (-i | --swaggerInput ) OPTIONS - -c , --configFile - Config file + -c , --config + Config file. + + -d , --outputDir + Output directory. Converts the Swagger specification into multiple + files. + + -f , --outputFile + Output file. Converts the Swagger specification into one file. -h, --help Display help information - -i , --inputFile - Input file. Can either be a URL or a file. + -i , --swaggerInput + Swagger input. Can either be a URL or a file path. - -o , --outputPath - Output path. Can either be a directory or a file. ---- @@ -51,10 +57,10 @@ You can convert a Swagger file into a folder as follows: [source, subs="attributes"] ---- -java -jar swagger2markup-cli-1.0.0-SNAPSHOT.jar convert -i /path/to/swagger_petstore.yaml -o /tmp +java -jar swagger2markup-cli-1.0.0-SNAPSHOT.jar convert -i /path/to/swagger_petstore.yaml -d /tmp/asiidoc ---- -It generates the Markup documents into the `/tmp` folder. +It generates the Markup documents into the `/tmp/asiidoc` folder. ==== Conversion into a file @@ -62,12 +68,12 @@ You can convert a local Swagger file into a file as follows: [source, subs="attributes"] ---- -java -jar swagger2markup-cli-1.0.0-SNAPSHOT.jar convert -i /path/to/swagger_petstore.yaml -o /tmp/swagger +java -jar swagger2markup-cli-1.0.0-SNAPSHOT.jar convert -i /path/to/swagger_petstore.yaml -f /tmp/asiidoc/swagger ---- NOTE: The input file must not have a file extension -It generates the Markup documents into the file `/tmp/swagger.adoc`. +It generates the Markup documents into the file `/tmp/asiidoc/swagger.adoc`. ==== Conversion of a remote Swagger file @@ -75,7 +81,7 @@ You can convert a remote Swagger specification which must be accessible via HTTP [source, subs="attributes"] ---- -java -jar swagger2markup-cli-1.0.0-SNAPSHOT.jar convert -i "http://petstore.swagger.io/v2/swagger.json" -o /tmp +java -jar swagger2markup-cli-1.0.0-SNAPSHOT.jar convert -i "http://petstore.swagger.io/v2/swagger.json" -d /tmp ---- ==== Configuration from a properties file diff --git a/src/docs/asciidoc/gradle_plugin.adoc b/src/docs/asciidoc/gradle_plugin.adoc index 7502aa13..27a4bdce 100644 --- a/src/docs/asciidoc/gradle_plugin.adoc +++ b/src/docs/asciidoc/gradle_plugin.adoc @@ -29,9 +29,9 @@ You can customize the task by configuring a Map of <> [source,groovy] ---- convertSwagger2markup { - swaggerInput file("src/docs/asciidoc") - markupOutputFile file("${buildDir}/asciidoc") - config = ['swagger2markup.markupLanguage' : 'ASCCIDOC', + input file("src/docs/swagger/swagger_petstore.yaml") + outputDir file("${buildDir}/asciidoc") + config = ['swagger2markup.markupLanguage' : 'ASCIIDOC', 'swagger2markup.pathsGroupedBy' : 'TAGS'] } @@ -40,14 +40,9 @@ convertSwagger2markup { [options="header"] .Gradle Plugin properties |==== -| Name | Description | Type | Example | Default -| swaggerInput | The directory or file path to the Swagger specification | File | `file("src/docs/swagger_petstore.yaml")` (file) or `file("src/docs/swagger")` (directory) | ``file("src/docs/swagger")`` -| markupOutputDir | The directory where the output should be stored. | String | `new File("/tmp/asciidoc")` | ``file("$buildDir/asciidoc")`` -| markupOutputFile | The file (without extensions) where the output should be stored. | String | ``file("$buildDir/asciidoc/swagger")`` | -| config | The Swagger2Markup properties to configure the converter | Map | ['swagger2markup.markupLanguage' : 'ASCCIDOC'] | +| Name | Description | Type | Example +| input | The URL or file path to the Swagger specification | String | `file("src/docs/swagger/swagger_petstore.yaml")` or `http://petstore.swagger.io/v2/swagger.json +| outputDir | The directory where the output should be stored. | File | `file("${buildDir}/asciidoc")` +| outputFile | The file path (without extension) where the output should be stored. | File | `file("${buildDir}/asciidoc/swagger")` +| config | The Swagger2Markup properties to configure the converter | Map | | |==== - - - - - diff --git a/src/docs/asciidoc/images/confluence_petstore_screenshot_1024.png b/src/docs/asciidoc/images/confluence_petstore_screenshot_1024.png new file mode 100644 index 00000000..7ad9b161 Binary files /dev/null and b/src/docs/asciidoc/images/confluence_petstore_screenshot_1024.png differ diff --git a/src/docs/asciidoc/images/overview_extension_points.png b/src/docs/asciidoc/images/overview_extension_points.png new file mode 100644 index 00000000..7c003123 Binary files /dev/null and b/src/docs/asciidoc/images/overview_extension_points.png differ diff --git a/src/docs/asciidoc/maven_plugin.adoc b/src/docs/asciidoc/maven_plugin.adoc index b162eb01..c7997e66 100644 --- a/src/docs/asciidoc/maven_plugin.adoc +++ b/src/docs/asciidoc/maven_plugin.adoc @@ -29,8 +29,8 @@ You can customize the task by configuring a Map of <> swagger2markup-maven-plugin {project-version} - ${project.basedir}/src/docs/swagger - ${project.build.directory}/asciidoc + ${project.basedir}/src/docs/swagger/swagger_petstore.yaml + ${project.build.directory}/asciidoc ASCIIDOC @@ -41,11 +41,12 @@ You can customize the task by configuring a Map of <> [options="header"] -.Gradle Plugin properties +.Maven Plugin properties |==== -| Name | Description | Type | Example | Default -| input | The URL, directory or file path to the Swagger specification | String | `src/docs/swagger_petstore.yaml` (file) or `"src/docs/swagger` (directory) | ``${project.basedir}/src/docs/swagger`` -| output | The directory or file (without extension) where the output should be stored. | String | `/tmp/asciidoc` or `/tmp/asciidoc/swagger` | ``${project.build.directory}/asciidoc`` -| config | The Swagger2Markup properties to configure the converter | Map | | | +| Name | Description | Type | Example +| input | The URL file path to the Swagger specification | String | `${project.basedir}/src/docs/swagger/swagger_petstore.yaml` or `http://petstore.swagger.io/v2/swagger.json` +| outputDir | The directory where the output should be stored. | File | `${project.build.directory}/asciidoc` +| outputFile | The file path (without extension) where the output should be stored. | File | `${project.build.directory}/asciidoc/swagger` +| config | The Swagger2Markup properties to configure the converter | Map | | |====