spring-api-scanner

spring-api-scanner

Scan a Spring Boot Java/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

npm install
npm run build

Serve generated docs:

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

Export static docs only:

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

Scan directly from Bitbucket repo + branch:

node dist/index.js --repo https://bitbucket.org/acme/orders-service.git --branch develop --no-serve --output ./api-docs

CLI

spring-api-scanner --help

Usage: spring-api-scanner <projectPath> [options]
       spring-api-scanner --repo <git-url> [options]

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

Options:
  --repo <url>         Clone and scan from a remote git repository (supports Bitbucket)
  --branch <name>      Branch to clone with --repo (default: main)
  --keep-clone         Keep cloned repo directory after scan (default: cleanup)
  --serve              Start a local server to serve the generated docs
  --no-serve           Only generate static files (default)
  --port <number>      Port for the server (default: 3000)
  --output <path>      Output directory for generated files (default: ./api-docs)
  --title <string>     API title for documentation (default: "Spring API Docs")
  --version <string>   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 schemas (including reactive wrappers like Mono<T>/Flux<T>)
• DTO schemas from Kotlin data class, Java class, and Java record
• Enum schemas from Kotlin enum class and Java enum
• 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
• Schema naming toggle - Switch schema and example keys between snake_case and camelCase
• Example payloads - Request/response example JSON generated from resolved schema
• Copy curl - One-click copy for curl commands
• Download - Export OpenAPI JSON

Naming Strategy Notes

Schema field names follow these rules:

• Kotlin DTO default naming: snake_case
• Java DTO default naming: camelCase
• If class has @JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy::class), fields become snake_case
• If class has @JsonNaming(PropertyNamingStrategies.LowerCamelCaseStrategy::class), fields stay camelCase

The UI naming toggle only changes how schema/example keys and curl body keys are displayed. It does not rewrite the generated openapi.json source of truth.

Type Coverage Notes

Common Java/Kotlin/JVM types are mapped, including:

• Scalars: String, Char, char, Int, int, Integer, Long, long, Short, short, Byte, byte, unsigned numeric variants, Boolean, boolean, Float, float, Double, double, BigDecimal, BigInteger
• Date/time: Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime
• Other common types: UUID, ByteArray, Any
• Collections/wrappers: List, Set, Collection, Page, Array, primitive arrays, Java arrays (T[]), Map, ResponseEntity<T>, Mono<T>, Flux<T>, Publisher<T>, Optional<T>
• Generic DTO classes with concrete arguments (for Kotlin data class, Java class, and Java record), e.g. ApiResponse<UserDto>

Generic DTO component names are materialized with type arguments (example: ApiResponseOfUserDto) to keep schema resolution deterministic.

Development

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