TestDriven Documentation. SpringRestDocs. SpringFox. Swagger2Markup. Asciidoctor.

BOOT LOGO

Build Status star this repo fork this repo License: MIT

Test Driven Development is a new approach that was provided by spring rest docs framework.

It expands classical Test Driven Development by adding new phase - documentation. It allows to combine manually written documentation and autogenerated snippets from tests(mockmvc, restassured). You can be sure that your documentation is always up to date.

There results of built documentation are published to github pages: https://tsypuk.github.io/springrestdoc/

Projects

SpringFox

SpringFox allows us to integrate SpringBoot app with swagger documentation. To start using it, you need to:

  1. Add dependencies: 
    compile 'io.springfox:springfox-swagger2:2.6.1'
compile 'io.springfox:springfox-swagger-ui:2.6.1'
  2. Mark your SpringApplication.class with @EnableSwagger2 annotation
  3. Register @Bean Docket
  4. Mark your code with io.swagger.annotations

Now you have two more things in your application:

  1. The swagger specification in json form by address: 
    http://localhost:8080/v2/api-docs?group=Module API
  2. The swagger UI page followed by URL: 
    http://localhost:8080/swagger-ui.html

SpringRestDocs

AsciiDoctor is awesome

Example of how to use diagrams in our documentation.

Swagger2Markup

I'm showing the pipeline, that allows to migrate your project from swagger to asciidoc and start using spring rest docs Test Driven Documentation.

It can be done in two ways:

  1. Using swaggerToMarkUp maven/gradle plugins
  2. By using io.github.swagger2markup from tests.

This two flows are implemented.

Plus like bonus you can move your swagger resource to git markdown/ confluence wiki formats. See tests.

TODO ITEMS