{"id":49292201,"url":"https://github.com/retreever-org/retreever-spring","last_synced_at":"2026-05-30T20:01:11.569Z","repository":{"id":325790294,"uuid":"1102387741","full_name":"retreever-org/retreever-spring","owner":"retreever-org","description":"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.","archived":false,"fork":false,"pushed_at":"2026-05-10T04:33:39.000Z","size":5127,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T06:45:45.433Z","etag":null,"topics":["api-testing-tool","documentation-generator"],"latest_commit_sha":null,"homepage":"https://retreever.dev","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/retreever-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-23T11:23:18.000Z","updated_at":"2026-05-10T04:33:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"a17bd76e-2648-4350-a897-f428951e0221","html_url":"https://github.com/retreever-org/retreever-spring","commit_stats":null,"previous_names":["retreever-org/retreever-java"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/retreever-org/retreever-spring","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retreever-org%2Fretreever-spring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retreever-org%2Fretreever-spring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retreever-org%2Fretreever-spring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retreever-org%2Fretreever-spring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/retreever-org","download_url":"https://codeload.github.com/retreever-org/retreever-spring/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retreever-org%2Fretreever-spring/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33707328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-testing-tool","documentation-generator"],"created_at":"2026-04-26T01:00:31.023Z","updated_at":"2026-05-30T20:01:11.563Z","avatar_url":"https://github.com/retreever-org.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Retreever\n\nRetreever is a Spring Boot library that turns your running application into a\nlive API documentation and testing workspace.\n\nAdd the dependency, start the app, open `/retreever`.\n\nRetreever reads the code you already have: controllers, request and response\ntypes, validation rules, headers, path variables, exception handlers, and nested\nDTOs. No separate spec file is required.\n\n## Install\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003edev.retreever\u003c/groupId\u003e\n    \u003cartifactId\u003eretreever\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n### Explore\n\n```text\nhttp://localhost:8080/retreever\n```\n\n**Read Detailed Docs Here:** https://docs.retreever.dev\n\n## What It Resolves\n\n- `@RestController` endpoints\n- request bodies and response types\n- path variables, query parameters, and headers\n- Jakarta Validation constraints\n- `@RestControllerAdvice` and `@ExceptionHandler` responses\n- records, nested DTOs, arrays, maps, and generic types\n- optional Retreever metadata annotations\n\n## Spring Security\n\nIf the host application uses Spring Security, allow Retreever routes through the\nhost security chain. Retreever's own optional auth runs inside the library after\nthat.\n\n```java\n@Bean\nSecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {\n    return http\n            .authorizeHttpRequests(auth -\u003e auth\n                    .requestMatchers(RetreeverPublicPaths.get()).permitAll()\n                    .anyRequest().authenticated()\n            )\n            .build();\n}\n```\n\n## Optional Annotations\n\nRetreever works without annotations. Use them when you want cleaner grouping,\nnames, examples, or error documentation.\n\n| Annotation | Purpose |\n| --- | --- |\n| `@ApiDoc` | API name, description, and version |\n| `@ApiGroup` | Controller grouping |\n| `@ApiEndpoint` | Endpoint name, description, status, security flag, headers, and mapped errors |\n| `@ApiError` | Exception-handler status and description |\n| `@FieldInfo` | Field description and example |\n| `@Description` | Parameter or field description |\n| `@RetreeverSkip` | Excludes a controller or endpoint from Retreever documentation |\n\n```java\n@ApiGroup(name = \"Product APIs\")\n@RestController\n@RequestMapping(\"/api/v1/products\")\nclass ProductController {\n\n    @ApiEndpoint(\n            name = \"Create Product\",\n            secured = true,\n            headers = {HttpHeaders.AUTHORIZATION}\n    )\n    @PostMapping\n    ResponseEntity\u003cProductResponse\u003e create(@RequestBody @Valid ProductRequest request) {\n        return null;\n    }\n}\n```\n\n## Configuration\n\nConfiguration is optional. Retreever is designed to start with no YAML.\n\n### Disable Retreever\n\n```properties\nretreever.enabled=false\n```\n\nThis is a hard disable. Retreever registers no controllers, filters, resource\nhandlers, scanners, UI routes, or documentation endpoints. Requests to\n`/retreever/**` fall through to the host application.\n\n### Exclude Endpoints From Documentation\n\nUse `@RetreeverSkip` on a controller class or method when endpoints must never\nappear in Retreever documentation, even if they also have `@ApiEndpoint`.\n\n```java\n@RetreeverSkip\n@RestController\n@RequestMapping(\"/internal\")\nclass InternalController {\n\n    @GetMapping(\"/reindex\")\n    void reindex() {\n    }\n}\n```\n\nHost applications can also exclude paths centrally:\n\n```yaml\nretreever:\n  docs:\n    skip:\n      - /internal/reindex\n      - /users/{userId}\n      - /admin/**\n      - 'regex:^/reports/[{]reportId[}]/export$'\n```\n\n`retreever.docs.skip` accepts exact paths, Spring/Ant-style patterns such as\n`/users/{userId}` and `/admin/**`, and regex entries prefixed with `regex:`.\nRegex entries are evaluated against Retreever's resolved endpoint path template.\nThis gives teams a compliance control for keeping sensitive or operational\nendpoints out of generated API documentation without changing the endpoints\nthemselves.\n\n### Retreever Auth\n\nSet both username and password to protect Retreever's internal APIs:\n\n```yaml\nretreever:\n  auth:\n    username: Admin\n    password: Admin@123\n    secret: 123e4567-e89b-12d3-a456-426614174000\n```\n\n`secret` signs Retreever auth tokens. Set the same UUID on every instance when\nthe app runs behind load balancing or across restarts where existing Retreever\nsessions should remain valid. If omitted, Retreever generates a startup-only\nsecret and old sessions become invalid after restart.\n\nRetreever auth cookies use the `Secure` attribute by default. In case a local\nHTTP-only development setup does not retain the Retreever login session, use\n`retreever.auth.secure-cookies=false` temporarily for that local setup only.\n\nIf username or password is missing, Retreever auth is disabled. Full auth\nbehavior is documented in\n[Documentation/Retreever-Auth-API.md](Documentation/Retreever-Auth-API.md).\n\n### Environment Variables\n\nStatic values:\n\n```yaml\nretreever:\n  env:\n    variable:\n      name: device-id\n      value: device-web-001\n```\n\nProperties form: `retreever.env.variable.name` and\n`retreever.env.variable.value`.\n\nValues resolved from API responses:\n\n```yaml\nretreever:\n  env:\n    variables:\n      - name: access-token\n        from:\n          endpoints:\n            - '[POST] /api/v1/public/login'\n            - '[GET] /api/v1/public/login/refresh'\n          extract:\n            - '[BODY] data.access_token'\n            - '[BODY] accessToken'\n\n      - name: session-id\n        from:\n          endpoints:\n            - '[POST] /api/v1/public/login'\n          extract:\n            - '[HEADER] X-Session-ID'\n            - '[HEADER] x-session-id'\n```\n\n## Compatibility\n\n- Spring Boot `3.x`\n- Java `17+`\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretreever-org%2Fretreever-spring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fretreever-org%2Fretreever-spring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretreever-org%2Fretreever-spring/lists"}