justin-sk / spring-restdocs

Test-driven documentation for RESTful services

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-restdocs tag.
• 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.