# spring-projects/spring-restdocs

Test-driven documentation for RESTful services

Repository: https://github.com/spring-projects/spring-restdocs
Canonical: https://ross.abutalabs.com/products/spring-restdocs
Homepage: https://spring.io/projects/spring-restdocs
Language: Java
License: Apache-2.0
License Family: permissive
Last push: 2026-06-11T08:33:11+00:00

## Health v2 (maintenance only)
Score: 85/100 (v2, computed 2026-09-02T17:46:02.011165+00:00)
- activity 87, release rhythm 75, longevity 100
- inputs: {"age_days": 4347, "days_push": 83, "days_rel": 85, "gap_med": 78.0, "n_releases_24m": 7}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1182, forks 730 (observed 2026-08-28T04:03:54.293995+00:00)

## What it is
Spring REST Docs is a Java library that generates accurate documentation for RESTful APIs by combining hand-written Asciidoctor content with auto-generated snippets produced during tests using Spring MVC Test. It produces readable, test-verified user-guide-style documentation rather than dense auto-generated API specs like Swagger.

## Use cases
- document rest api endpoints from tests
- generate api documentation with spring boot
- produce accurate restful service docs
- generate openapi spec from spring tests
- avoid stale swagger documentation
- document request and response payloads in junit tests

## When to choose
- you want documentation that is guaranteed accurate because it is generated from passing tests
- you prefer concise, hand-crafted guides over fully automated dense API references
- your stack is Spring Boot or Spring MVC with JUnit or TestNG tests

## When to avoid
- you want zero-effort, fully automatic API docs from code annotations alone
- your services are not on the JVM or not testable with Spring MVC Test
- you need interactive API explorer UIs like Swagger UI out of the box

## Facets
- artifact type: library
- maturity: active
- function: testing, api-documentation, documentation
- domain: documentation, testing, apis, web-development, developer-tools
- platform: jvm, cli
- tags: rest-api, asciidoctor, spring, spring-mvc-test, api-docs, test-driven-documentation, openapi

## Member repositories
- spring-projects/spring-restdocs (main) score 85

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:03:54.293995+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T06:24:59.149390+00:00, confidence not recorded.
  - readme: https://github.com/spring-projects/spring-restdocs (fetched 2026-08-28T04:03:54.293995+00:00, sha 188861685686)
  - homepage: https://spring.io/projects/spring-restdocs (fetched 2026-08-29T12:31:52.089354+00:00, sha 1e2a101b77d3)
  - site_page: https://spring.io/quickstart (fetched 2026-08-29T12:31:52.101653+00:00, sha fc64dd950363)
  - site_page: https://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle (fetched 2026-08-29T12:31:52.107483+00:00, sha bd6a812a3a95)
  - site_page: https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-testing.html (fetched 2026-08-29T12:31:52.109865+00:00, sha a2ebaede3a78)
  - site_page: https://enterprise.spring.io (fetched 2026-08-29T12:31:52.099066+00:00, sha 85ac7d6d5114)
  - site_page: https://enterprise.spring.io/lts-releases (fetched 2026-08-29T12:31:52.104398+00:00, sha 3251cc8760b6)
- Data as of 2026-08-30T08:39:29.467469+00:00.