anchor.diff:  
   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.
  +==== Include JSON and XML Schema files.
   Swagger2Markup can also include JSON and XML Schema files into the generated document.
   
   [source,java]
  
positive.code: 
  Using the Swagger2MarkupConverter is simple.  For example, if you are using https://github.com/spring-projects/spring-boot[Spring Boot] and https://github.com/springfox/springfox[springfox], you can generate your Swagger JSON file during the integration or unit test phase, convert the Swagger file into AsciiDoc, convert AsciiDoc into HTML and PDF, copy the documentation into the Jar file and serve it as static content. That way there is no runtime overhead and there are no additional runtime library dependencies required.
  The quickest way to get started is to look at the demo project https://github.com/RobWin/spring-swagger2markup-demo[spring-swagger2markup-demo]. The demo shows how to generate static docs (HTML5 and PDF) with the https://github.com/RobWin/swagger2markup-gradle-plugin[Swagger2Markup Gradle Plugin] and serve them as static content in a Spring Boot App under http://localhost:9080/docs/index.html and http://localhost:9080/docs/index.pdf.
  
  
  ==== Generate Markup during an integration test
  
  
negative.code:     }
  }
  ----
  
  ==== Include spring-restdocs example snippets
  
  Swagger2Markup can be used together with https://github.com/spring-projects/spring-restdocs[spring-restdocs]. Swagger2Markup can include the generated HTTP request and response example 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");
  }
  ----
  
  By convention the target folder of the generated request and response example files must be similar to the value of the ApiOperation, but with underscores and lowercase. For example a folder for `@ApiOperation(value = "Add a new pet to the store")` must be called `add_a_new_pet_to_the_store`.
  
  [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,groovy]
  ----
  ext {
      generatedDocumentation = file('src/docs/asciidoc/generated')
  }
  
  test {
      systemProperty 'io.springfox.staticdocs.outputDir', generatedDocumentation
      outputs.dir generatedDocumentation
  }
  ----
  
  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("src/docs/asciidoc")
                      .withExamples("src/docs/asciidoc/generated").build())
              .andExpect(status().isOk());
  }
  ----
  
  By convention the Swagger2MarkupConverter searches for a method annotated with `@ApiOperation(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.
  
  The AsciiDoc HTML output would look as follows:
  
  image::images/springrestdocs_examples.PNG[springrestdocs]
  
  ==== Include hand-written descriptions into the generated documentation
  
  