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/

• SpringFox Swagger.
• SpringRestDocs.
• AsciiDoctor is awesome.
• Swagger2Markdown.

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

Example of how to use diagrams in our documentation.

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.

• Create springboot app for springfox (swagger annotations).
• Create springboot app restdos.
• Create springboot app ascidocisawsome. To show advanced features and diagrams.
• Create springboot app swagger2markup. Migration.
• Add build to static resource pdf/html in jar.
• Internal/External Docs. public to git pages.