anchor.diff:  
   You can generate your HTML5 and PDF documentation via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin]. The following listing shows how to configure the Asciidoctor Gradle plugin. By default it searches for AsciiDoc files in `src/docs/asciidoc` and puts the HTML and PDF output into `build/asciidoc/html5` and `build/asciidoc/pdf`. The `generated` attribute is used to provide configurable access to the generated snippets. The system property is used to control the base directory to which the documents are generated.
   
  -[source]
  +[source,groovy]
   ----
   ext {
       generatedDocumentation = file('src/docs/asciidoc/generated')
  
positive.code: 
  image::images/handwritten_descr_asciidoc.PNG[handwritten_descr_asciidoc]
  
  == Examples
  == 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]
  
  
  == Integration with spring-restdocs
  Swagger2Markup can be used together with https://github.com/spring-projects/spring-restdocs[spring-restdocs]. Swagger2Markup can include the generated HTTP request and response snippets from spring-restdocs into the generated AsciiDoc document. See https://github.com/spring-projects/spring-restdocs[spring-restdocs] how to configure it.
  Currently spring-restdocs does only support AsciiDoc.
  
  Let's say you have a Swagger-annotated Spring RestController method with an ApiOperation value: `Add a new pet to the store`
  
  [source,java]
  ----
  @RequestMapping(method = POST)
  @ApiOperation(value = "Add a new pet to the store")
  @ApiResponses(value = {@ApiResponse(code = 405, message = "Invalid input")})
  public ResponseEntity<String> addPet(
        @ApiParam(value = "Pet object that needs to be added to the store", required = true) @RequestBody Pet pet) {
      petData.add(pet);
      return Responses.ok("SUCCESS");
  }
  ----
  
  The target folder of the generated request and response example files must be `add_a_new_pet_to_the_store` (similar to the value of the ApiOperation, but with underscores and lowercase).
  
  [source,java]
  ----
  @Test
  public void findPetById() throws Exception {
      this.mockMvc.perform(post("/api/pet/").content(createPet())
              .contentType(MediaType.APPLICATION_JSON))
              .andDo(RestDocumentation.document("add_a_new_pet_to_the_store"))
              .andExpect(status().isOk());
  }
  ----
  
  The spring-restdocs output directory is configured as follows:
  
  [source]
  ----
  org.springframework.restdocs.outputDir = src/docs/asciidoc/generated
  ----
  
  You must specify the base output directory of spring-restdocs with the builder method `withExamples("src/docs/asciidoc/generated")`.
  
  [source,java]
  ----
  @Test
  public void convertToAsciiDoc() throws Exception {
      this.mockMvc.perform(get("/v2/api-docs")
              .accept(MediaType.APPLICATION_JSON))
              .andDo(Swagger2MarkupResultHandler.outputDirectory("swagger_adoc")
                      .withExamples("src/docs/asciidoc/generated").build())
              .andExpect(status().isOk());
  }
  ----
  
  The Swagger2MarkupConverter searches for a Swagger ApiOperation with value `Add a new pet to the store` in a folder called `src/docs/asciidoc/generated/add_a_new_pet_to_the_store` and includes the `http-request.adoc` and `http-response.adoc` files, if they are available.
  
  === Generated AsciiDoc
  image::images/springrestdocs_examples.PNG[springrestdocs]
  
  
  == Integration of JSON and XML Schema files.
  Swagger2Markup can also include JSON and XML Schema files into the generated document.
  
  [source,java]
  
negative.code: 
  Swagger2Markup converts a Swagger JSON or YAML file into several *AsciiDoc* or *GitHub Flavored Markdown* documents which can be combined with hand-written documentation. The Swagger source file can be located locally or remotely via HTTP. Swagger2Markup supports the Swagger 1.2 and 2.0 specification. Internally it uses the _official_ https://github.com/swagger-api/swagger-parser[swagger-parser] and my https://github.com/RobWin/markup-document-builder[markup-document-builder]. 
  
  You can use Swagger2Markup to convert your design-first Swagger YAML file into a human-readable format and combine it with hand-written documentation. As an alternative, you can choose the implementation-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 usage guide below. If you are are Gradle user, you can also use the https://github.com/RobWin/swagger2markup-gradle-plugin[Swagger2Markup Gradle Plugin].
  
  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 https://github.com/asciidoctor/asciidoctorj[asciidoctorj] or even better via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin] or https://github.com/asciidoctor/asciidoctor-maven-plugin[asciidoctor-maven-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 guide
  
  === Adding Swagger2Markup to your project
  The project is published in JCenter and Maven Central.
  