Spring REST Docs: API documentation assembled from the tests you already write

The documentation comes out of the test suite

The primary goal of Spring REST Docs, in the README's own words, is to make it easy to document RESTful services by combining content that has been hand-written using Asciidoctor with auto-generated examples produced with the Spring MVC Test framework.

That combination is the whole idea, and it is different from the usual approach. In a schema-driven setup, a specification file describes the API and a generator turns it into reference pages. Here, the reference pages are written by a person, and the parts that are tedious to write by hand, the actual request and response payloads, are captured by running the real code in a test and recording what came back.

The result is described as an easy-to-read user guide, akin to GitHub's API documentation, rather than the fully automated, dense API documentation produced by tools like Swagger.

The distinction is one of authorship. The prose is a human artefact that can be reviewed, argued over and written in the order a reader needs, and the examples are machine artefacts that cannot drift from the code, because they are produced by the same request the test makes. The trade is coverage: the documentation is exactly as complete as the test suite, and a team that documents an endpoint by writing a test for it gets a guarantee, while a team that wants coverage of endpoints nobody has tested gets nothing from this approach.

The project is part of the Spring ecosystem, published at spring.io/projects/spring-restdocs, licensed under the Apache 2.0 licence, and the reference documentation lives at docs.spring.io/spring-restdocs/docs.

The module split shows what the library actually is

The repository layout is a good map of the design, because every directory is a piece of the pipeline.

spring-restdocs-core
spring-restdocs-asciidoctor
spring-restdocs-mockmvc
spring-restdocs-resttestclient
spring-restdocs-webtestclient
spring-restdocs-platform
spring-restdocs-bom

core holds the abstractions: the request, response and snippet model, and the mechanisms that turn a recorded exchange into a snippet you can drop into a document. The asciidoctor module is the Asciidoctor integration, which is what lets a written document pull in a generated request and response block at a marked position rather than pasting it by hand.

Then there is one module per test client. mockmvc is for the MockMvc approach, resttestclient is for RestTemplate, and webtestclient is for the newer WebTestClient. The fact that there are three of them says the library's job is to sit on top of whatever HTTP testing style the project already uses, rather than asking the team to change it.

The platform module is the shared internal one, the bom is the dependency management module for the family, and the docs module holds the reference documentation itself, with an antora directory for the documentation site and a separate spring-restdocs-docs module.

The result is a project where the core is small and the value is spread across adapters, which is the shape you want from something that has to fit into an existing test suite rather than replace it.

Building it needs Java 17 and Gradle

The build instructions are short, which is what you would expect from a project that is a library rather than an application.

You will need Java 17 or later to build Spring REST Docs, and it is built using Gradle:

./gradlew build

The repository carries the Gradle wrapper with gradlew and gradlew.bat, a settings.gradle, a build.gradle and gradle.properties, and a .sdkmanrc file for SDKMAN users. There is also a .idea directory, a config directory and a git directory, and the CI runs on GitHub Actions with a build and deploy snapshot workflow, along with a build status badge and a Develocity build scan badge.

Two release lines are visible in the release history, and they matter for a library. Version 3.0.6 and version 4.0.1 were both published on 2026-06-09, a few minutes apart, and version 4.0.0 came on 2025-11-19.

Publishing two lines from the same repository on the same day is the standard arrangement for a library that has to keep supporting users on an older major version. A team on Spring Boot that has not yet moved to the 4.x line can take the 3.0.x fixes, and the fixes are built from the same commit history rather than from a fork.

The last push to the repository was on 2026-10-15, so the 4.x line is the one that is being worked on, and the 3.x line is the one that is being kept alive.

The extensions cover what the core cannot reach

The README lists third-party extensions, and the list reads as a map of the gaps in the core.

restdocs-wiremock auto-generates WireMock stubs as part of documenting your RESTful API, which is what you need when the documentation has to be reproducible rather than merely readable. restdocsext-jersey enables Spring REST Docs to be used with Jersey's test framework, which matters for teams that did not choose Spring MVC. spring-auto-restdocs uses introspection and Javadoc to automatically document request and response parameters, which is the closest thing in the ecosystem to the generated reference that the core deliberately avoids.

The fourth, restdocs-api-spec, adds API specification support and currently supports OpenAPI 2 and OpenAPI 3.

That last one deserves attention because it undercuts the choice. The usual argument against a documentation-as-test approach is that you cannot emit a machine-readable contract from it, and the existence of an extension that does exactly that means the difference between the two approaches is a matter of how much you want to hand-write, not a matter of capability.

So the honest way to frame the choice is not test-driven versus generated. It is a narrative guide that happens to be assembled from test output, against a reference generated from a schema, and a project can have both by using this library for the guide and the specification extension for the contract. The cost of that combination is that two descriptions of the same API exist and can disagree.

Where it is the wrong tool

The limitation follows from the mechanism, and it is worth stating plainly to anyone whose API has more surface than their test suite.

Spring REST Docs documents what your tests exercise. An endpoint that no test calls is not documented, and there is no mechanism in this library that discovers endpoints, because discovery is not what it does. For an API with a hundred endpoints and tests for twenty of them, the guide will cover twenty, and nothing will complain. The failure is silent, which is the worst kind for documentation, because the guide looks complete.

The second limitation is the Asciidoctor coupling. The output format is a written document, not a structured API description, and the integration between the two is a build step that has to be configured rather than a library call. A team that wants documentation to exist in a portal, in a searchable form, or in a format a client generator can consume, is working against the design rather than with it.

The third is the cost of the writing. The approach only pays off if someone writes the prose, and that is a recurring human cost rather than a one-off generation. Where the API is large and mostly uninteresting, the ratio is poor, and a smaller team is better served by a specification with generated examples.

None of that makes the library wrong. It makes it a choice about who does the writing, and the choice is worth making deliberately rather than by default.

Editorial conclusion

Spring REST Docs fits a team that wants its API guide written and reviewed by people rather than emitted by a schema, and that already tests its controllers with Spring MVC Test. It does not fit an API surface nobody has written tests for, and it does not fit a project that wants a live, machine-readable contract as its primary artefact. Before adopting it, check that the endpoints you need to document are already covered by MockMvc or TestRestTemplate tests, and read how the Asciidoctor snippets are pulled in, because that integration is where the setup cost sits.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. spring-projects/spring-restdocs on GitHub