diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..1df421a --- /dev/null +++ b/README.adoc @@ -0,0 +1,275 @@ += Swagger2Markup Maven Plugin +:author: RedOwl Analytics +:version: 0.6.3 +:hardbreaks: + +image:https://travis-ci.org/redowl/swagger2markup-maven-plugin.svg["Build Status", link="https://travis-ci.org/redowl/swagger2markup-maven-plugin"] image:https://coveralls.io/repos/redowl/swagger2markup-maven-plugin/badge.svg["Coverage Status", link="https://coveralls.io/r/redowl/swagger2markup-maven-plugin"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"] image:https://img.shields.io/badge/Twitter-redowlytics-blue.svg["Twitter", link="https://twitter.com/redowlytics"] + +== Overview + +The primary goal of https://github.com/RobWin/swagger2markup[Swagger2Markup] is to *simplify the generation of an up-to-date RESTful API documentation by combining documentation that's been hand-written with auto-generated API documentation* produced by https://github.com/swagger-api[Swagger]. The result is intended to be an *up-to-date, easy-to-read, on- and offline user guide*, comparable to https://developer.github.com/v3/[GitHub's API documentation]. The output of the plugin can be used as an alternative to https://github.com/swagger-api/swagger-ui[swagger-ui] and can be served as static content. + +The Swagger2Markup Maven Plugin simplifies the usage of https://github.com/RobWin/swagger2markup[Swagger2Markup]. The Plugin adds a Maven goal which converts a Swagger JSON or YAML file into several *AsciiDoc* or *GitHub Flavored Markdown* documents. The plugin supports the Swagger 1.2 and 2.0 specification. Internally the plugin uses https://github.com/RobWin/swagger2markup[Swagger2Markup] which in turn uses the _official_ https://github.com/swagger-api/swagger-parser[swagger-parser] and RobWin's https://github.com/RobWin/markup-document-builder[markup-document-builder]. + +You can use the plugin to convert your contract-first Swagger YAML file into a human-readable format and combine it with hand-written documentation. As an alternative, you can choose the code-first approach and use Swagger2Markup together with https://github.com/swagger-api/swagger-core/tree/master/samples/java-jersey2[Swagger JAX-RS], https://github.com/springfox/springfox[springfox] or https://github.com/spring-projects/spring-restdocs[spring-restdocs]. See https://github.com/RobWin/swagger2markup#using-swagger2markup[Swagger2Markup user guide] for more details. + +http://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc] is preferable to Markdown as it has more features. AsciiDoc is a text document format for writing documentation, articles, books, ebooks, slideshows, web pages and blogs. AsciiDoc files can be converted to *HTML*, *PDF* and *EPUB*. AsciiDoc is much better suited for describing public APIs than *JavaDoc* or *Annotations*. + +You can generate your HTML5, PDF and EPUB documentation via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin]. You can also use https://github.com/jbake-org/jbake[JBake], https://github.com/tomchristie/mkdocs[MkDocs], https://github.com/rtfd/readthedocs.org[ReadTheDocs] or https://github.com/tripit/slate[slate] to publish your AsciiDoc or Markdown documentation. + +The project requires at least JDK 7. + +== Usage + +_COMING SOON_: The project will be published in Maven Central. + +Add the following snippet to your Maven pom file: + +[source,xml] +[subs="specialcharacters,attributes"] +---- +... + + + com.redowlanalytics + swagger2markup-maven-plugin + {version} + ... + + +... +---- + +The plugin adds a new task goal `swagger2markup:process-swagger`. This goal exposes a few properties as part of its configuration. + +.Properties +[horizontal] +inputDirectory:: specifies the directory where the swagger source is located. Use `inputDir file('src/docs/swagger')` + Default: `${project.basedir}/src/docs/swagger`. +outputDirectory:: specifies the directory where the output should be stored. Use `outputDir file("${buildDir}/asciidoc")` + Default: `${project.build.directory}/${swagger2markup.markupLanguage}`. +examplesDirectory:: specifies the directory where example snippets from spring-restdocs are located. + Default: empty (not mandatory) +descriptionsDirectory:: specifies the directory where hand-written descriptions are located. + Default: empty (not mandatory) +schemasDirectory:: specifies the directory where JSON or XML schema files are located. + Default: empty (not mandatory) +markupLanguage:: specifies the markup output format. + Values: Any supported MarkupLanguage - Can be `asciidoc` or `markdown` + Default: `asciidoc` +separateDefinitions:: creates separate definition files for each model. + Default: `false` + +=== Example + +[source,xml] +[subs="specialcharacters,attributes"] +---- + + + com.redowlanalytics + swagger2markup-maven-plugin + {version} + + src/docs/swagger + src/docs/asciidoc/generated + src/docs/asciidoc + src/docs/schema + true + + + +---- + +The configuration above would result in call to Swagger2Markup as follows: + +[source, java] +---- +Swagger2MarkupConverter.from("src/docs/swagger") + .withExamples("src/docs/asciidoc/generated") + .withDescriptions("src/docs/asciidoc") + .withSchemas("src/docs/schemas") + .withSeparateDefinitions().build() + .intoFolder("build/asciidoc"); +---- + +=== Full example + +==== Maven pom file + +[source,xml] +[subs="specialcharacters,attributes"] +---- + + + 4.0.0 + + com.redowlanalytics + swagger2markup-sample + 1.0-SNAPSHOT + + + ${project.basedir}/src/main/swagger + ${project.build.directory}/generated-docs + ${base.generated.docs.dir}/asciidoc + ${project.basedir}/src/main/asciidoc + ${base.generated.docs.dir}/html + ${base.generated.docs.dir}/pdf + + + + + + + com.redowlanalytics + swagger2markup-maven-plugin + {version} + + ${swagger.input.directory} + ${generated.asciidoc.directory} + asciidoc + + + + + + org.asciidoctor + asciidoctor-maven-plugin + 1.5.2 + + + + org.asciidoctor + asciidoctorj-pdf + 1.5.0-alpha.7 + + + + + ${asciidoctor.input.directory} + index.adoc + + book + left + 2 + ${generated.asciidoc.directory} + + + + + + output-html + generate-resources + + process-asciidoc + + + html5 + ${asciidoctor.html.output.directory} + + + + output-pdf + generate-resources + + process-asciidoc + + + pdf + ${asciidoctor.pdf.output.directory} + + + + + + + + maven-resources-plugin + 2.7 + + + copy-resources + process-resources + + copy-resources + + + ${project.build.outputDirectory}/static/docs + + + ${asciidoctor.html.output.directory} + + + ${asciidoctor.pdf.output.directory} + + + + + + + + + +---- + +==== Generate Swagger JSON during an unit test with springfox-staticdocs + +[source,java] +---- +@WebAppConfiguration +@RunWith(SpringJUnit4ClassRunner.class) +@ContextConfiguration(classes = Application.class, loader = SpringApplicationContextLoader.class) +public class Swagger2MarkupTest { + + @Autowired + private WebApplicationContext context; + + private MockMvc mockMvc; + + @Before + public void setUp() { + this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) + .apply(new RestDocumentationConfigurer()).build(); + } + + @Test + public void createSwaggerJson() throws Exception { + String outputDir = System.getProperty("io.springfox.staticdocs.outputDir"); + this.mockMvc.perform(get("/v2/api-docs") + .accept(MediaType.APPLICATION_JSON)) + .andDo(SwaggerResultHandler.outputDirectory(outputDir).build()) + .andExpect(status().isOk()); + } +} +---- + +== Screenshots +=== Swagger source +image::images/swagger_json.PNG[swagger_json] + +=== Generated AsciiDoc +image::images/asciidoc.PNG[asciidoc] + +=== Generated Markdown +image::images/markdown.PNG[markdown] + +=== Generated HTML using AsciidoctorJ +image::images/asciidoc_html.PNG[asciidoc_html] + +=== Generated PDF using AsciidoctorJ +image::images/asciidoc_pdf.PNG[asciidoc_pdf] + +== License + +Copyright 2015 RedOwl Analytics + +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. diff --git a/images/asciidoc.PNG b/images/asciidoc.PNG new file mode 100644 index 0000000..979d69a Binary files /dev/null and b/images/asciidoc.PNG differ diff --git a/images/asciidoc_html.PNG b/images/asciidoc_html.PNG new file mode 100644 index 0000000..0873bba Binary files /dev/null and b/images/asciidoc_html.PNG differ diff --git a/images/asciidoc_pdf.PNG b/images/asciidoc_pdf.PNG new file mode 100644 index 0000000..ed5cb60 Binary files /dev/null and b/images/asciidoc_pdf.PNG differ diff --git a/images/markdown.PNG b/images/markdown.PNG new file mode 100644 index 0000000..1300d00 Binary files /dev/null and b/images/markdown.PNG differ diff --git a/images/swagger_json.PNG b/images/swagger_json.PNG new file mode 100644 index 0000000..5b7f953 Binary files /dev/null and b/images/swagger_json.PNG differ diff --git a/src/main/java/com/redowlanalytics/swagger2markup/Swagger2MarkupMojo.java b/src/main/java/com/redowlanalytics/swagger2markup/Swagger2MarkupMojo.java index 0814eb6..f5e3cf6 100644 --- a/src/main/java/com/redowlanalytics/swagger2markup/Swagger2MarkupMojo.java +++ b/src/main/java/com/redowlanalytics/swagger2markup/Swagger2MarkupMojo.java @@ -21,10 +21,10 @@ public class Swagger2MarkupMojo extends AbstractMojo { private static final String PREFIX = "swagger2markup."; - @Parameter(property = PREFIX + "inputDirectory", defaultValue = "${basedir}/src/docs/swagger", required = true) + @Parameter(property = PREFIX + "inputDirectory", defaultValue = "${project.basedir}/src/docs/swagger", required = true) private File inputDirectory; - @Parameter(property = PREFIX + "outputDirectory", defaultValue = "${project.build.directory}/src/docs/swagger", required = true) + @Parameter(property = PREFIX + "outputDirectory", required = true) private File outputDirectory; @Parameter(property = PREFIX + "markupLanguage", defaultValue = "asciidoc", required = true)