spring-api-scanner 0.1.0

package/PLAN.md

@@ -0,0 +1,142 @@
+# Spring API Scanner Implementation Plan
+
+## Goal
+Build a standalone CLI tool that scans a Spring Boot Kotlin codebase and outputs:
+- OpenAPI 3.0 JSON (`openapi.json`)
+- A clean, minimal, detailed UI for human-readable API browsing
+
+No dependency changes are required in the target Spring service.
+
+## One-Shot Usage
+- Serve UI + OpenAPI:
+  - `npx spring-api-scanner /path/to/service --serve`
+- Export static docs only:
+  - `npx spring-api-scanner /path/to/service --no-serve --output ./api-docs`
+
+## Scope
+Extract and visualize per endpoint:
+- Endpoint name (controller method name)
+- HTTP method + full path
+- Path variables
+- Query params
+- Request headers
+- Request body schema
+- Response body schema
+
+## Architecture
+- **CLI**: Node.js + TypeScript
+- **Kotlin parsing**: `tree-sitter-kotlin`
+- **Spec generation**: OpenAPI 3.0 builder
+- **UI**: static SPA (search/filter/expandable details)
+
+Pipeline:
+1. Scan Kotlin files
+2. Parse Spring annotations and signatures
+3. Resolve DTO schemas
+4. Generate OpenAPI JSON
+5. Render UI data model
+6. Serve or export static output
+
+## Tasks
+
+### 1) CLI Skeleton
+- Implement command:
+  - `spring-api-scanner <projectPath> [--port] [--output] [--serve] [--title] [--version]`
+- Validate input path and print scan summary.
+
+Acceptance:
+- CLI runs and produces placeholder output.
+
+### 2) Endpoint Extraction (Spring Kotlin)
+- Scan `src/main/kotlin/**/*.kt`.
+- Parse:
+  - `@RestController`
+  - class-level `@RequestMapping`
+  - method mappings: `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`, `@RequestMapping(method=...)`
+- Extract:
+  - method, path, operation name
+  - `@PathVariable`, `@RequestParam`, `@RequestHeader`, `@RequestBody`
+  - return type
+
+Acceptance:
+- Real fixture project produces accurate endpoint list.
+
+### 3) DTO & Type Resolver
+- Parse Kotlin `data class` definitions.
+- Resolve nested DTOs recursively.
+- Nullability (`?`) => optional fields.
+- Unwrap wrappers (`ResponseEntity<T>`, `List<T>`, `Page<T>`).
+- Type mapping examples:
+  - `String -> string`
+  - `Long -> integer (int64)`
+  - `Int -> integer (int32)`
+  - `Boolean -> boolean`
+  - `Double -> number (double)`
+  - `Instant -> string (date-time)`
+
+Acceptance:
+- Request/response schemas include concrete fields where resolvable.
+
+### 4) OpenAPI 3.0 Generator
+- Build `openapi.json` with:
+  - `openapi`, `info`, `paths`, `components.schemas`
+- For each operation include:
+  - `operationId`, `tags`, `parameters`, `requestBody`, `responses`
+- Emit header params as `in: header`.
+
+Acceptance:
+- Spec validates in Swagger Editor.
+
+### 5) Human-Readable UI
+- Clean minimal detailed UI with:
+  - Search by endpoint/path
+  - Filter by method/controller
+  - Expandable endpoint cards
+  - Sections: path vars, query params, headers, request body, response body
+  - Download OpenAPI JSON
+  - Copy curl
+- Responsive for desktop/mobile.
+
+Acceptance:
+- No missing endpoint metadata for supported annotation patterns.
+
+### 6) One-Shot Orchestration
+- End-to-end command flow:
+  - scan -> resolve -> generate -> render -> serve/export
+- Modes:
+  - `--serve`: host UI + `/openapi.json`
+  - `--no-serve --output`: write static output
+
+Acceptance:
+- One command consistently produces both machine + human outputs.
+
+### 7) Edge Cases & Robustness
+- Support annotation forms:
+  - positional value, `value=`, `path=`, arrays
+- Handle unresolved DTOs as warnings (no crash).
+- Skip non-controller files safely.
+
+Acceptance:
+- Tool is stable on mixed real-world projects.
+
+### 8) Testing Strategy
+- Unit tests:
+  - parser
+  - type mapping
+  - OpenAPI generation
+- Integration tests with realistic Kotlin fixtures.
+- Golden-file test for deterministic `openapi.json` output.
+
+Acceptance:
+- CI-friendly deterministic test suite passes.
+
+## Deliverables
+- `spring-api-scanner` CLI
+- Generated `openapi.json`
+- Generated/served API catalog UI
+- README with quickstart and examples
+
+## Definition of Done
+- One command produces valid OpenAPI JSON and complete UI docs.
+- Endpoint cards include: name, path vars, params, headers, request/response bodies.
+- Works without any dependency/code changes in the target Spring service.

package/README.md

@@ -0,0 +1,60 @@
+# 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`)
+
+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
+
+```text
+spring-api-scanner <projectPath> [--port] [--output] [--serve] [--no-serve] [--title] [--version]
+```
+
+## 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`
+
+## 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`.

package/dist/args.d.ts

@@ -0,0 +1,9 @@
+export interface CliOptions {
+    projectPath: string;
+    port: number;
+    output: string;
+    serve: boolean;
+    title: string;
+    version: string;
+}
+export declare function parseCliArgs(argv: string[]): CliOptions;

package/dist/args.js

@@ -0,0 +1,57 @@
+const DEFAULT_PORT = 3000;
+const DEFAULT_OUTPUT = "./api-docs";
+const DEFAULT_TITLE = "Spring API Docs";
+const DEFAULT_VERSION = "1.0.0";
+export function parseCliArgs(argv) {
+    if (argv.length === 0 || argv[0].startsWith("--")) {
+        throw new Error("A project path is required: spring-api-scanner <projectPath>");
+    }
+    const projectPath = argv[0];
+    const options = {
+        projectPath,
+        port: DEFAULT_PORT,
+        output: DEFAULT_OUTPUT,
+        serve: false,
+        title: DEFAULT_TITLE,
+        version: DEFAULT_VERSION
+    };
+    for (let i = 1; i < argv.length; i += 1) {
+        const token = argv[i];
+        switch (token) {
+            case "--serve":
+                options.serve = true;
+                break;
+            case "--no-serve":
+                options.serve = false;
+                break;
+            case "--port":
+                options.port = parseIntegerFlag("--port", argv[++i]);
+                break;
+            case "--output":
+                options.output = parseStringFlag("--output", argv[++i]);
+                break;
+            case "--title":
+                options.title = parseStringFlag("--title", argv[++i]);
+                break;
+            case "--version":
+                options.version = parseStringFlag("--version", argv[++i]);
+                break;
+            default:
+                throw new Error(`Unknown argument: ${token}`);
+        }
+    }
+    return options;
+}
+function parseStringFlag(flagName, rawValue) {
+    if (!rawValue || rawValue.startsWith("--")) {
+        throw new Error(`Missing value for ${flagName}`);
+    }
+    return rawValue;
+}
+function parseIntegerFlag(flagName, rawValue) {
+    const parsed = Number.parseInt(parseStringFlag(flagName, rawValue), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${flagName} must be a positive integer`);
+    }
+    return parsed;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseCliArgs } from "./args.js";
+import { writePlaceholderArtifacts } from "./output.js";
+import { scanDataClasses } from "./resolver.js";
+import { scanSpringProject } from "./scanner.js";
+async function main() {
+    const options = parseCliArgs(process.argv.slice(2));
+    await validateProjectPath(options.projectPath);
+    const endpoints = await scanSpringProject(options.projectPath);
+    const types = await scanDataClasses(options.projectPath);
+    const output = await writePlaceholderArtifacts(options, endpoints, types);
+    printSummary(options, endpoints.length, output.warnings);
+    if (options.serve) {
+        await serveOutput(options.output, options.port);
+    }
+}
+async function validateProjectPath(projectPath) {
+    const result = await stat(projectPath).catch(() => null);
+    if (!result || !result.isDirectory()) {
+        throw new Error(`Project path not found or not a directory: ${projectPath}`);
+    }
+}
+function printSummary(options, endpointCount, warnings) {
+    console.log("Spring API Scanner");
+    console.log(`- Project: ${path.resolve(options.projectPath)}`);
+    console.log(`- Output: ${path.resolve(options.output)}`);
+    console.log(`- Endpoints discovered: ${endpointCount}`);
+    console.log("- OpenAPI: openapi.json written");
+    console.log(`- Warnings: ${warnings.length}`);
+    for (const warning of warnings.slice(0, 5)) {
+        console.log(`  - ${warning}`);
+    }
+    console.log(`- Serve mode: ${options.serve ? "enabled" : "disabled"}`);
+}
+async function serveOutput(outputDir, port) {
+    const root = path.resolve(outputDir);
+    const server = createServer(async (req, res) => {
+        const pathname = req.url === "/openapi.json"
+            ? "openapi.json"
+            : req.url === "/ui-data.json"
+                ? "ui-data.json"
+                : "index.html";
+        const fullPath = path.join(root, pathname);
+        try {
+            const contents = await readFile(fullPath);
+            const contentType = pathname === "index.html" ? "text/html; charset=utf-8" : "application/json; charset=utf-8";
+            res.writeHead(200, { "content-type": contentType });
+            res.end(contents);
+        }
+        catch {
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+        }
+    });
+    server.listen(port, () => {
+        console.log(`Serving docs at http://localhost:${port}`);
+    });
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+});

package/dist/openapi.d.ts

@@ -0,0 +1,67 @@
+import type { ExtractedEndpoint } from "./scanner.js";
+import { type KotlinTypeRegistry } from "./resolver.js";
+export interface OpenApiSchema {
+    type?: string;
+    format?: string;
+    items?: OpenApiSchema;
+    properties?: Record<string, OpenApiSchema>;
+    required?: string[];
+    $ref?: string;
+}
+export interface OpenApiParameter {
+    in: "path" | "query" | "header";
+    name: string;
+    required: boolean;
+    schema: OpenApiSchema;
+}
+export interface OpenApiResponse {
+    description: string;
+    content: {
+        "application/json": {
+            schema: OpenApiSchema;
+        };
+    };
+}
+export interface OpenApiOperation {
+    operationId: string;
+    tags: string[];
+    parameters: OpenApiParameter[];
+    requestBody?: {
+        required: boolean;
+        content: {
+            "application/json": {
+                schema: OpenApiSchema;
+            };
+        };
+    };
+    responses: Record<string, OpenApiResponse | {
+        description: string;
+    }>;
+}
+export interface OpenApiDocument {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    paths: Record<string, Record<string, OpenApiOperation>>;
+    components: {
+        schemas: Record<string, OpenApiSchema>;
+    };
+}
+export interface OpenApiArtifacts {
+    document: OpenApiDocument;
+    warnings: string[];
+}
+export declare function buildOpenApiDocument(input: {
+    title: string;
+    version: string;
+    endpoints: ExtractedEndpoint[];
+    types: KotlinTypeRegistry;
+}): OpenApiDocument;
+export declare function buildOpenApiArtifacts(input: {
+    title: string;
+    version: string;
+    endpoints: ExtractedEndpoint[];
+    types: KotlinTypeRegistry;
+}): OpenApiArtifacts;

package/dist/openapi.js

@@ -0,0 +1,94 @@
+import { resolveSchemaForType } from "./resolver.js";
+export function buildOpenApiDocument(input) {
+    return buildOpenApiArtifacts(input).document;
+}
+export function buildOpenApiArtifacts(input) {
+    const schemas = {};
+    const paths = {};
+    const context = { warnings: new Set() };
+    for (const endpoint of input.endpoints) {
+        const method = endpoint.httpMethod.toLowerCase();
+        const parameters = [
+            ...endpoint.pathVariables.map((item) => ({
+                in: "path",
+                name: item.name,
+                required: true,
+                schema: resolveSchemaForType(item.type, input.types, schemas, new Set(), context)
+            })),
+            ...endpoint.queryParams.map((item) => ({
+                in: "query",
+                name: item.name,
+                required: item.required ?? false,
+                schema: resolveSchemaForType(item.type, input.types, schemas, new Set(), context)
+            })),
+            ...endpoint.headers.map((item) => ({
+                in: "header",
+                name: item.name,
+                required: item.required ?? false,
+                schema: resolveSchemaForType(item.type, input.types, schemas, new Set(), context)
+            }))
+        ];
+        const requestBody = endpoint.requestBody
+            ? {
+                required: endpoint.requestBody.required,
+                content: {
+                    "application/json": {
+                        schema: resolveSchemaForType(endpoint.requestBody.type, input.types, schemas, new Set(), context)
+                    }
+                }
+            }
+            : undefined;
+        const response = buildOperationResponse(endpoint, input.types, schemas, context);
+        const operation = {
+            operationId: endpoint.operationName,
+            tags: [guessTag(endpoint.sourceFile)],
+            parameters,
+            ...(requestBody ? { requestBody } : {}),
+            responses: response
+        };
+        if (!paths[endpoint.fullPath]) {
+            paths[endpoint.fullPath] = {};
+        }
+        paths[endpoint.fullPath][method] = operation;
+    }
+    return {
+        document: {
+            openapi: "3.0.3",
+            info: {
+                title: input.title,
+                version: input.version
+            },
+            paths,
+            components: {
+                schemas
+            }
+        },
+        warnings: [...context.warnings]
+    };
+}
+function guessTag(sourceFile) {
+    const file = sourceFile.replaceAll("\\", "/").split("/").at(-1) ?? sourceFile;
+    return file.endsWith(".kt") ? file.slice(0, -3) : file;
+}
+function buildOperationResponse(endpoint, types, schemas, context) {
+    const normalizedReturn = endpoint.returnType.trim();
+    const isNoContent = normalizedReturn === "Unit" || normalizedReturn === "Void";
+    if (isNoContent) {
+        return {
+            "204": {
+                description: "No Content"
+            }
+        };
+    }
+    const statusCode = endpoint.httpMethod === "POST" ? "201" : "200";
+    return {
+        [statusCode]: {
+            description: statusCode === "201" ? "Created" : "OK",
+            content: {
+                "application/json": {
+                    schema: resolveSchemaForType(endpoint.returnType, types, schemas, new Set(), context)
+                }
+            }
+        }
+    };
+}

package/dist/output.d.ts

@@ -0,0 +1,6 @@
+import type { CliOptions } from "./args.js";
+import type { KotlinTypeRegistry } from "./resolver.js";
+import type { ExtractedEndpoint } from "./scanner.js";
+export declare function writePlaceholderArtifacts(options: CliOptions, endpoints: ExtractedEndpoint[], types: KotlinTypeRegistry): Promise<{
+    warnings: string[];
+}>;

package/dist/output.js

@@ -0,0 +1,25 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildOpenApiArtifacts } from "./openapi.js";
+import { buildUiModel, renderUiHtml } from "./ui.js";
+export async function writePlaceholderArtifacts(options, endpoints, types) {
+    const outputDir = path.resolve(options.output);
+    const openApiPath = path.join(outputDir, "openapi.json");
+    const uiDataPath = path.join(outputDir, "ui-data.json");
+    const indexPath = path.join(outputDir, "index.html");
+    const artifacts = buildOpenApiArtifacts({
+        title: options.title,
+        version: options.version,
+        endpoints,
+        types
+    });
+    const uiModel = buildUiModel({
+        endpoints,
+        openapi: artifacts.document
+    });
+    await mkdir(outputDir, { recursive: true });
+    await writeFile(openApiPath, JSON.stringify(artifacts.document, null, 2), "utf8");
+    await writeFile(uiDataPath, JSON.stringify(uiModel, null, 2), "utf8");
+    await writeFile(indexPath, renderUiHtml(options.title, uiModel), "utf8");
+    return { warnings: artifacts.warnings };
+}

package/dist/resolver.d.ts

@@ -0,0 +1,17 @@
+export interface KotlinProperty {
+    name: string;
+    type: string;
+    nullable: boolean;
+}
+export interface KotlinDataClass {
+    name: string;
+    namingStrategy: "snake_case" | "camelCase";
+    properties: KotlinProperty[];
+}
+export type KotlinTypeRegistry = Record<string, KotlinDataClass>;
+export interface ResolutionContext {
+    warnings: Set<string>;
+}
+export declare function scanDataClasses(projectPath: string): Promise<KotlinTypeRegistry>;
+export declare function parseDataClassesFromSource(source: string): KotlinTypeRegistry;
+export declare function resolveSchemaForType(rawType: string, registry: KotlinTypeRegistry, components: Record<string, unknown>, seen?: Set<string>, context?: ResolutionContext): Record<string, unknown>;