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.

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.

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

Retreever is published to Maven Central.

<dependency>
    <groupId>dev.retreever</groupId>
    <artifactId>retreever</artifactId>
    <version>1.0.0</version>
</dependency>

After adding the dependency, start the application and open:

/retreever

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():

@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.

Retreever works without custom annotations, but these help produce cleaner and more intentional documentation:

@SpringBootApplication
@ApiDoc(
        name = "Catalog API",
        description = "Live API docs for the catalog service",
        version = "v1"
)
public class CatalogApplication {
}

@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<ApiResponse<ProductVariantResponse>> 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<ApiErrorResponse> handleAccessDenied(AccessDeniedException ex) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN)
                .body(ApiErrorResponse.build("Access Denied", ex.getMessage()));
    }
}

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
) {}

All Retreever configuration is optional.

Use configuration only when you want to enhance documentation or behavior.

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:

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.

Retreever can define static environment values or extract them from API responses for testing workflows.

Example:

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

• 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

Issues, bug reports, integration tests, resolver improvements, and UI feedback are all welcome.

MIT