ff18f8034d
AsciidoctorJ 1.6 is not backwards compatible with AsciidoctorJ 1.5 and AsciidoctorJ 2.0 is not backwards compatible with AsciidoctorJ 1.6 or 1.5. The backwards incompatibilities are such that they cannot be worked around using reflection so code needs to be compiled against each of the three versions. To this end, this commit splits spring-restdocs-asciidoctor into several separate modules: 1. spring-restdocs-asciidoctor-support 2. spring-restdocs-asciidoctor-1.5 3. spring-restdocs-asciidoctor-1.6 4. spring-restdocs-asciidoctor-2.0 spring-restdocs-asciidoctor-support contains support code that is not tied to a specific version of AsciidoctorJ and can be used with 1.5, 1.6 and 2.0. The other three modules contain code that is specific to a particular version of AsciidoctorJ. Each version-specific module uses class names that are unique across all three modules and is written in such a way that they will back off when used in an environment with a different version of AsciidoctorJ. The existing spring-restdocs-asciidoctor module has been modified to merge the version specific jars and the support jar together into a single jar that supports AsciidoctorJ 1.5, 1.6, and 2.0. The above-described changes should allow users to depend upon spring-restdocs-asciidoctor as before and to now be able to use AsciidoctorJ 1.5, 1.6, or 2.0. Closes gh-581
Spring REST Docs 
Overview
The primary goal of this project is to make it easy to document RESTful services by combining content that's been hand-written using Asciidoctor with auto-generated examples produced with the Spring MVC Test framework. The result is intended to be an easy-to-read user guide, akin to GitHub's API documentation for example, rather than the fully automated, dense API documentation produced by tools like Swagger.
For a broader introduction see the Documenting RESTful APIs presentation. Both the slides and a video recording are available.
Learning more
To learn more about Spring REST Docs, please consult the reference documentation.
Building from source
You will need Java 8 or later to build Spring REST Docs. It is built using Gradle:
./gradlew build
Contributing
Contributors to this project agree to uphold its code of conduct.
There are several that you can contribute to Spring REST Docs:
- Open a pull request. Please see the contributor guidelines for details.
- Ask and answer questions on Stack Overflow using the
spring-restdocstag. - Chat with fellow users on Gitter.
Third-party extensions
| Name | Description |
|---|---|
| restdocs-wiremock | Auto-generate WireMock stubs as part of documenting your RESTful API |
| restdocsext-jersey | Enables Spring REST Docs to be used with Jersey's test framework |
| spring-auto-restdocs | Uses introspection and Javadoc to automatically document request and response parameters |
| restdocs-api-spec | A Spring REST Docs extension that adds API specification support. It currently supports OpenAPI 2 and OpenAPI 3 |
Licence
Spring REST Docs is open source software released under the Apache 2.0 license.