https://github.com/retreever-org/retreever-spring
Retreever is a lightweight, developer-first toolkit that automatically discovers your Spring Boot APIs and generates a clean, test-ready documentation model — zero configuration required.
https://github.com/retreever-org/retreever-spring
api-testing-tool documentation-generator
Last synced: 27 days ago
JSON representation
Retreever is a lightweight, developer-first toolkit that automatically discovers your Spring Boot APIs and generates a clean, test-ready documentation model — zero configuration required.
- Host: GitHub
- URL: https://github.com/retreever-org/retreever-spring
- Owner: retreever-org
- License: mit
- Created: 2025-11-23T11:23:18.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T20:06:06.000Z (about 1 month ago)
- Last Synced: 2026-04-14T22:10:22.835Z (about 1 month ago)
- Topics: api-testing-tool, documentation-generator
- Language: Java
- Homepage: https://retreever.dev
- Size: 4.84 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Retreever
Retreever is a lightweight, developer-first toolkit for generating live API
documentation and API testing UI for Spring Boot applications.
It scans your controllers, request and response models, validation constraints,
and exception handlers to build documentation from the application code that is
already running.
Add the dependency, start the application, open `/retreever`.
## Zero Config First
Retreever is designed to work with zero configuration.
- No YAML is required
- No annotations are required
- No separate documentation layer is required
Annotations and properties are optional add-ons for improving documentation,
grouping, examples, auth, and testing experience.
The main integration case to handle manually is when the host application uses
Spring Security. In that case, Retreever's public routes need to be allowed.
## What Retreever Resolves
Retreever automatically reads and resolves:
- `@RestController` endpoints
- Request bodies and response types
- Path variables, query parameters, and headers
- Validation constraints from Jakarta Validation annotations
- Exception mappings from `@RestControllerAdvice` and `@ExceptionHandler`
- Nested DTOs, arrays, maps, records, and generic types
- Endpoint metadata such as name, description, status, and security flags
The generated document includes:
- API name, description, and version
- Endpoint groups
- HTTP method, path, consumes, and produces metadata
- Request and response schemas
- Parameter and header metadata
- Error responses
## Installation
Retreever is published to Maven Central.
```xml
dev.retreever
retreever
1.0.0
```
After adding the dependency, start the application and open:
```text
/retreever
```
## Spring Security Integration
If the host application uses Spring Security, all Retreever routes must be
allowed through the application's security configuration.
Host security should not protect Retreever endpoints directly. Retreever's own
library-level auth handles `/retreever/doc`, `/retreever/ping`, and
`/retreever/environment` internally after the request is allowed into the
library.
Use `RetreeverPublicPaths.get()`:
```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
return http
.authorizeHttpRequests(auth -> auth
.requestMatchers(RetreeverPublicPaths.get()).permitAll()
.anyRequest().authenticated()
)
.build();
}
```
This is the main setup step required when Retreever is added to a secured host
application.
## Optional Annotations
Retreever works without custom annotations, but these help produce cleaner and
more intentional documentation:
| Annotation | Purpose |
| --- | --- |
| `@ApiDoc` | Sets top-level API name, description, and version |
| `@ApiGroup` | Groups controller endpoints under a named section |
| `@ApiEndpoint` | Adds endpoint name, description, status, security flag, headers, and mapped errors |
| `@ApiError` | Documents exception-handler status and description |
| `@FieldInfo` | Adds field descriptions and example values |
| `@Description` | Adds descriptions to request parameters and fields |
## Example Usage
### Application Metadata
```java
@SpringBootApplication
@ApiDoc(
name = "Catalog API",
description = "Live API docs for the catalog service",
version = "v1"
)
public class CatalogApplication {
}
```
### Group, Endpoint, Errors, and Field Metadata
```java
@ApiGroup(
name = "Product Variant APIs",
description = "APIs for managing product variants"
)
@RestController
@RequestMapping("/api/v1")
public class ProductVariantController {
@ApiEndpoint(
name = "Create Product Variant",
description = "Create a new product variant",
secured = true,
headers = {HttpHeaders.AUTHORIZATION, "X-Device-ID"},
errors = {
AccessDeniedException.class,
ProductNotFoundException.class,
MethodArgumentNotValidException.class
}
)
@PostMapping("/products/{productId}/variants")
public ResponseEntity> createVariant(
@Description("ID/Primary Key of the product to which the variant should belong.")
@PathVariable Long productId,
@RequestBody @Valid ProductVariantRequest request
) {
return null;
}
@ApiError(
status = HttpStatus.FORBIDDEN,
description = "Access Denied"
)
@ExceptionHandler(AccessDeniedException.class)
public ResponseEntity handleAccessDenied(AccessDeniedException ex) {
return ResponseEntity.status(HttpStatus.FORBIDDEN)
.body(ApiErrorResponse.build("Access Denied", ex.getMessage()));
}
}
```
```java
public record ProductVariantRequest(
@FieldInfo(
example = "Red Mug - Ceramic",
description = "User-friendly name of the product variant. Required."
)
@NotBlank(message = "Title must not be blank")
@Size(min = 1, max = 255, message = "Title length must be between 1 and 255 characters")
@JsonProperty("title")
String title
) {}
```
## Optional Configuration
All Retreever configuration is optional.
Use configuration only when you want to enhance documentation or behavior.
### Optional Retreever Auth
Retreever authentication is optional.
If the host sets both username and password, Retreever protects its private
tool APIs internally. If the host does not set them, Retreever auth is fully
disabled and the tool remains publicly accessible inside the host application.
When auth should be enabled, set:
```properties
retreever.auth.username=Admin
retreever.auth.password=Admin@123
retreever.auth.secret=123e4567-e89b-12d3-a456-426614174000
```
Token TTLs default to:
- access token: `30 minutes`
- refresh token: `7 days`
Override token expiration only if you actually need different values.
`retreever.auth.secret` is optional. When set, it must be a valid UUID string.
Use the same UUID on all service instances that must trust the same Retreever
cookies. If omitted, Retreever generates a startup-only secret and existing
cookies become invalid after restart.
`retreever.auth.secure-cookies` defaults to `false`. Set it to `true` when the
host serves Retreever over HTTPS and you want auth cookies emitted with the
`Secure` attribute.
If auth is disabled because username and password are not configured, Retreever
ignores `retreever.auth.secret` and TTL settings entirely.
`retreever.dev.allow-cross-origin` is contributor-only. It exists for
developing Retreever's React UI against a separate local dev server and is
only honored when Retreever itself is running from local exploded classes.
If Retreever is running as a packaged dependency jar inside a consuming
application, this setting is ignored and Retreever stays same-origin only.
Detailed auth behavior is documented in
[Documentation/Retreever-Auth-API.md](Documentation/Retreever-Auth-API.md).
### Optional Environment Variable Resolution
Retreever can define static environment values or extract them from API
responses for testing workflows.
Example:
```yaml
retreever:
env:
variables:
- name: access-token
source:
request:
endpoints:
- /api/v1/public/login
- /api/v1/public/login/refresh
method: post
response:
body-attribute-path: data.access_token
- name: refresh-token
source:
request:
endpoints:
- /api/v1/public/login
- /api/v1/public/login/refresh
method: post
response:
body-attribute-path: data.refresh_token
- name: device-id
source:
value: device-web-001
```
## Compatibility
- Release line `1.x` targets Spring Boot `3.x`
- Minimum Java version is `17`
- Spring Boot `4.x` support is planned for a future major version
## Contributing
Issues, bug reports, integration tests, resolver improvements, and UI feedback
are all welcome.
## License
MIT