spring-api-scanner

Scan a Spring Boot Kotlin service and generate:

- openapi.json (OpenAPI 3.0)
- A static API catalog UI (index.html + ui-data.json)
- Structured warnings (scan-warnings.json)

No code/dependency changes are required in the target Spring service.

Quickstart

``bash
npm install
npm run build
`

Serve generated docs:

`bash
node dist/index.js /path/to/spring-service --serve --port 3000
`

Export static docs only:

`bash
node dist/index.js /path/to/spring-service --no-serve --output ./api-docs
`

CLI

`bash
spring-api-scanner --help
`

`text
Usage: spring-api-scanner [options]

Scan a Spring Boot Kotlin project and generate OpenAPI documentation and a static UI.

Options:
--serve Start a local server to serve the generated docs
--no-serve Only generate static files (default)
--port Port for the server (default: 3000)
--output Output directory for generated files (default: ./api-docs)
--title API title for documentation (default: "Spring API Docs")
--version API version for documentation (default: 1.0.0)
--strict Exit with non-zero code on unresolved critical issues
--help Show this help message
`

What It Extracts

- @RestController
- Class-level @RequestMapping
- Method mappings:
- @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping
- @RequestMapping(method = ...)
- Parameters:
- @PathVariable, @RequestParam, @RequestHeader, @RequestBody
- Return type and DTO schemas from Kotlin data class
- Enum schemas from Kotlin enum class
- Validation hints from common annotations (@NotNull, @Size)

UI Features

The generated UI includes:
- Search with keyboard shortcut (/) - Press / to focus the search box
- Deep-linking - Copy and share direct links to endpoints
- Filter persistence - Filter selections are saved to localStorage
- Collapsible schemas - Expand/collapse request/response body schemas
- Copy curl - One-click copy for curl commands
- Download - Export OpenAPI JSON

Naming Strategy Notes

Schema field names follow these rules:

- Default DTO naming: snake_case
- If class has @JsonNaming(PropertyNamingStrategies.LowerCamelCaseStrategy::class), fields stay camelCase

Development

`bash
npm test
npm run build
`

Integration + golden-file tests are under tests/integration.test.ts and tests/golden/openapi.sample-service.json.

Roadmap

See docs/ROADMAP.md for phased priorities (v0.2, v0.3, v1.0`).