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: about 1 month 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 (8 months ago)
- Default Branch: main
- Last Pushed: 2026-05-10T04:33:39.000Z (2 months ago)
- Last Synced: 2026-05-10T06:45:45.433Z (2 months ago)
- Topics: api-testing-tool, documentation-generator
- Language: Java
- Homepage: https://retreever.dev
- Size: 4.89 MB
- Stars: 4
- 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 Spring Boot library that turns your running application into a
live API documentation and testing workspace.
Add the dependency, start the app, open `/retreever`.
Retreever reads the code you already have: controllers, request and response
types, validation rules, headers, path variables, exception handlers, and nested
DTOs. No separate spec file is required.
## Install
```xml
dev.retreever
retreever
1.1.0
```
### Explore
```text
http://localhost:8080/retreever
```
**Read Detailed Docs Here:** https://docs.retreever.dev
## What It Resolves
- `@RestController` endpoints
- request bodies and response types
- path variables, query parameters, and headers
- Jakarta Validation constraints
- `@RestControllerAdvice` and `@ExceptionHandler` responses
- records, nested DTOs, arrays, maps, and generic types
- optional Retreever metadata annotations
## Spring Security
If the host application uses Spring Security, allow Retreever routes through the
host security chain. Retreever's own optional auth runs inside the library after
that.
```java
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
return http
.authorizeHttpRequests(auth -> auth
.requestMatchers(RetreeverPublicPaths.get()).permitAll()
.anyRequest().authenticated()
)
.build();
}
```
## Optional Annotations
Retreever works without annotations. Use them when you want cleaner grouping,
names, examples, or error documentation.
| Annotation | Purpose |
| --- | --- |
| `@ApiDoc` | API name, description, and version |
| `@ApiGroup` | Controller grouping |
| `@ApiEndpoint` | Endpoint name, description, status, security flag, headers, and mapped errors |
| `@ApiError` | Exception-handler status and description |
| `@FieldInfo` | Field description and example |
| `@Description` | Parameter or field description |
| `@RetreeverSkip` | Excludes a controller or endpoint from Retreever documentation |
```java
@ApiGroup(name = "Product APIs")
@RestController
@RequestMapping("/api/v1/products")
class ProductController {
@ApiEndpoint(
name = "Create Product",
secured = true,
headers = {HttpHeaders.AUTHORIZATION}
)
@PostMapping
ResponseEntity create(@RequestBody @Valid ProductRequest request) {
return null;
}
}
```
## Configuration
Configuration is optional. Retreever is designed to start with no YAML.
### Disable Retreever
```properties
retreever.enabled=false
```
This is a hard disable. Retreever registers no controllers, filters, resource
handlers, scanners, UI routes, or documentation endpoints. Requests to
`/retreever/**` fall through to the host application.
### Exclude Endpoints From Documentation
Use `@RetreeverSkip` on a controller class or method when endpoints must never
appear in Retreever documentation, even if they also have `@ApiEndpoint`.
```java
@RetreeverSkip
@RestController
@RequestMapping("/internal")
class InternalController {
@GetMapping("/reindex")
void reindex() {
}
}
```
Host applications can also exclude paths centrally:
```yaml
retreever:
docs:
skip:
- /internal/reindex
- /users/{userId}
- /admin/**
- 'regex:^/reports/[{]reportId[}]/export$'
```
`retreever.docs.skip` accepts exact paths, Spring/Ant-style patterns such as
`/users/{userId}` and `/admin/**`, and regex entries prefixed with `regex:`.
Regex entries are evaluated against Retreever's resolved endpoint path template.
This gives teams a compliance control for keeping sensitive or operational
endpoints out of generated API documentation without changing the endpoints
themselves.
### Retreever Auth
Set both username and password to protect Retreever's internal APIs:
```yaml
retreever:
auth:
username: Admin
password: Admin@123
secret: 123e4567-e89b-12d3-a456-426614174000
```
`secret` signs Retreever auth tokens. Set the same UUID on every instance when
the app runs behind load balancing or across restarts where existing Retreever
sessions should remain valid. If omitted, Retreever generates a startup-only
secret and old sessions become invalid after restart.
Retreever auth cookies use the `Secure` attribute by default. In case a local
HTTP-only development setup does not retain the Retreever login session, use
`retreever.auth.secure-cookies=false` temporarily for that local setup only.
If username or password is missing, Retreever auth is disabled. Full auth
behavior is documented in
[Documentation/Retreever-Auth-API.md](Documentation/Retreever-Auth-API.md).
### Environment Variables
Static values:
```yaml
retreever:
env:
variable:
name: device-id
value: device-web-001
```
Properties form: `retreever.env.variable.name` and
`retreever.env.variable.value`.
Values resolved from API responses:
```yaml
retreever:
env:
variables:
- name: access-token
from:
endpoints:
- '[POST] /api/v1/public/login'
- '[GET] /api/v1/public/login/refresh'
extract:
- '[BODY] data.access_token'
- '[BODY] accessToken'
- name: session-id
from:
endpoints:
- '[POST] /api/v1/public/login'
extract:
- '[HEADER] X-Session-ID'
- '[HEADER] x-session-id'
```
## Compatibility
- Spring Boot `3.x`
- Java `17+`
## License
MIT