spring-api-scanner 0.1.0

package/tests/golden/openapi.sample-service.json

@@ -0,0 +1,164 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Sample Service",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/api/users": {
+      "post": {
+        "operationId": "createUser",
+        "tags": [
+          "UserController"
+        ],
+        "parameters": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateUserRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/users/{id}": {
+      "delete": {
+        "operationId": "deleteUser",
+        "tags": [
+          "UserController"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No Content"
+          }
+        }
+      },
+      "get": {
+        "operationId": "getUser",
+        "tags": [
+          "UserController"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          },
+          {
+            "in": "query",
+            "name": "include_posts",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "header",
+            "name": "X-Trace-Id",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "CreateUserRequest": {
+        "type": "object",
+        "properties": {
+          "first_name": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "first_name",
+          "created_at"
+        ]
+      },
+      "UserProfile": {
+        "type": "object",
+        "properties": {
+          "avatar_url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "avatar_url"
+        ]
+      },
+      "UserResponse": {
+        "type": "object",
+        "properties": {
+          "userId": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "firstName": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "profile": {
+            "$ref": "#/components/schemas/UserProfile"
+          }
+        },
+        "required": [
+          "userId",
+          "firstName",
+          "createdAt"
+        ]
+      }
+    }
+  }
+}

package/tests/integration.test.ts

@@ -0,0 +1,98 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { buildOpenApiDocument } from "../src/openapi.js";
+import { scanDataClasses } from "../src/resolver.js";
+import { scanSpringProject } from "../src/scanner.js";
+
+describe("integration fixture", () => {
+  it("matches golden OpenAPI output deterministically", async () => {
+    const fixtureRoot = path.join(os.tmpdir(), `spring-api-scanner-fixture-${Date.now()}`);
+    const kotlinDir = path.join(fixtureRoot, "src", "main", "kotlin", "demo");
+    await mkdir(kotlinDir, { recursive: true });
+
+    await writeFile(
+      path.join(kotlinDir, "UserController.kt"),
+      `
+      package demo
+
+      import org.springframework.web.bind.annotation.DeleteMapping
+      import org.springframework.web.bind.annotation.GetMapping
+      import org.springframework.web.bind.annotation.PathVariable
+      import org.springframework.web.bind.annotation.PostMapping
+      import org.springframework.web.bind.annotation.RequestBody
+      import org.springframework.web.bind.annotation.RequestHeader
+      import org.springframework.web.bind.annotation.RequestMapping
+      import org.springframework.web.bind.annotation.RequestParam
+      import org.springframework.web.bind.annotation.RestController
+
+      @RestController
+      @RequestMapping("/api/users")
+      class UserController {
+        @GetMapping("/{id}")
+        fun getUser(
+          @PathVariable id: Long,
+          @RequestParam(required = false) includePosts: Boolean?,
+          @RequestHeader("X-Trace-Id") traceId: String
+        ): UserResponse {
+          TODO()
+        }
+
+        @PostMapping
+        fun createUser(@RequestBody body: CreateUserRequest): UserResponse {
+          TODO()
+        }
+
+        @DeleteMapping("/{id}")
+        fun deleteUser(@PathVariable id: Long): Unit {
+          TODO()
+        }
+      }
+      `,
+      "utf8"
+    );
+
+    await writeFile(
+      path.join(kotlinDir, "UserDtos.kt"),
+      `
+      package demo
+
+      import com.fasterxml.jackson.databind.PropertyNamingStrategies
+      import com.fasterxml.jackson.databind.annotation.JsonNaming
+      import java.time.Instant
+
+      data class CreateUserRequest(
+        val firstName: String,
+        val createdAt: Instant
+      )
+
+      @JsonNaming(PropertyNamingStrategies.LowerCamelCaseStrategy::class)
+      data class UserResponse(
+        val userId: Long,
+        val firstName: String,
+        val createdAt: Instant,
+        val profile: UserProfile?
+      )
+
+      data class UserProfile(
+        val avatarUrl: String
+      )
+      `,
+      "utf8"
+    );
+
+    const endpoints = await scanSpringProject(fixtureRoot);
+    const types = await scanDataClasses(fixtureRoot);
+
+    const document = buildOpenApiDocument({
+      title: "Sample Service",
+      version: "1.0.0",
+      endpoints,
+      types
+    });
+
+    const expected = await readFile(path.resolve("tests/golden/openapi.sample-service.json"), "utf8");
+    expect(JSON.stringify(document, null, 2)).toBe(expected.trim());
+  });
+});

package/tests/openapi.test.d.ts

@@ -0,0 +1 @@
+export {};

package/tests/openapi.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import { buildOpenApiArtifacts, buildOpenApiDocument } from "../src/openapi.js";
+
+describe("buildOpenApiDocument", () => {
+  it("creates openapi with endpoint params and concrete schemas", () => {
+    const spec = buildOpenApiDocument({
+      title: "Catalog API",
+      version: "0.2.0",
+      endpoints: [
+        {
+          sourceFile: "UserController.kt",
+          operationName: "createUser",
+          httpMethod: "POST",
+          fullPath: "/users",
+          returnType: "ResponseEntity<UserDto>",
+          pathVariables: [],
+          queryParams: [{ name: "include_posts", type: "Boolean?", required: false }],
+          headers: [{ name: "X-Trace-Id", type: "String", required: true }],
+          requestBody: { type: "CreateUserRequest", required: true }
+        }
+      ],
+      types: {
+        CreateUserRequest: {
+          name: "CreateUserRequest",
+          namingStrategy: "snake_case",
+          properties: [
+            { name: "name", type: "String", nullable: false },
+            { name: "age", type: "Int?", nullable: true }
+          ]
+        },
+        UserDto: {
+          name: "UserDto",
+          namingStrategy: "snake_case",
+          properties: [
+            { name: "id", type: "Long", nullable: false },
+            { name: "name", type: "String", nullable: false }
+          ]
+        }
+      }
+    });
+
+    expect(spec.openapi).toBe("3.0.3");
+    expect(spec.info.title).toBe("Catalog API");
+    expect(spec.info.version).toBe("0.2.0");
+    expect(spec.paths["/users"].post.operationId).toBe("createUser");
+    expect(spec.paths["/users"].post.parameters).toEqual([
+      {
+        in: "query",
+        name: "include_posts",
+        required: false,
+        schema: { type: "boolean" }
+      },
+      {
+        in: "header",
+        name: "X-Trace-Id",
+        required: true,
+        schema: { type: "string" }
+      }
+    ]);
+    expect(spec.paths["/users"].post.requestBody).toEqual({
+      required: true,
+      content: {
+        "application/json": {
+          schema: { $ref: "#/components/schemas/CreateUserRequest" }
+        }
+      }
+    });
+    expect(spec.paths["/users"].post.responses["201"].content["application/json"].schema).toEqual({
+      $ref: "#/components/schemas/UserDto"
+    });
+    expect(spec.paths["/users"].post.responses["200"]).toBeUndefined();
+    expect(spec.components.schemas.CreateUserRequest.required).toEqual(["name"]);
+  });
+
+  it("uses 204 and no content for Unit returns", () => {
+    const spec = buildOpenApiDocument({
+      title: "Catalog API",
+      version: "0.2.0",
+      endpoints: [
+        {
+          sourceFile: "UserController.kt",
+          operationName: "deleteUser",
+          httpMethod: "DELETE",
+          fullPath: "/users/{id}",
+          returnType: "Unit",
+          pathVariables: [{ name: "id", type: "Long" }],
+          queryParams: [],
+          headers: []
+        }
+      ],
+      types: {}
+    });
+
+    expect(spec.paths["/users/{id}"].delete.responses["204"]).toEqual({
+      description: "No Content"
+    });
+    expect(spec.paths["/users/{id}"].delete.responses["200"]).toBeUndefined();
+  });
+});
+
+describe("buildOpenApiArtifacts", () => {
+  it("collects unresolved type warnings without crashing", () => {
+    const result = buildOpenApiArtifacts({
+      title: "Catalog API",
+      version: "0.2.0",
+      endpoints: [
+        {
+          sourceFile: "UserController.kt",
+          operationName: "getUnknown",
+          httpMethod: "GET",
+          fullPath: "/unknown",
+          returnType: "MissingDto",
+          pathVariables: [],
+          queryParams: [],
+          headers: []
+        }
+      ],
+      types: {}
+    });
+
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings[0]).toMatch(/MissingDto/);
+    expect(
+      result.document.paths["/unknown"].get.responses["200"].content["application/json"].schema
+    ).toEqual({ type: "object" });
+  });
+});

package/tests/output.test.ts

@@ -0,0 +1,55 @@
+import { mkdir, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { writePlaceholderArtifacts } from "../src/output.js";
+import type { CliOptions } from "../src/args.js";
+import type { ExtractedEndpoint } from "../src/scanner.js";
+
+describe("writePlaceholderArtifacts", () => {
+  it("writes openapi, ui-data, and index html", async () => {
+    const root = path.join(os.tmpdir(), `scanner-out-${Date.now()}`);
+    await mkdir(root, { recursive: true });
+
+    const options: CliOptions = {
+      projectPath: root,
+      output: root,
+      serve: false,
+      port: 3000,
+      title: "Demo Docs",
+      version: "1.0.0"
+    };
+
+    const endpoints: ExtractedEndpoint[] = [
+      {
+        sourceFile: "UserController.kt",
+        operationName: "getUser",
+        httpMethod: "GET",
+        fullPath: "/users/{id}",
+        returnType: "UserDto",
+        pathVariables: [{ name: "id", type: "Long", required: true }],
+        queryParams: [],
+        headers: []
+      }
+    ];
+
+    const result = await writePlaceholderArtifacts(options, endpoints, {
+      UserDto: {
+        name: "UserDto",
+        namingStrategy: "snake_case",
+        properties: [{ name: "id", type: "Long", nullable: false }]
+      }
+    });
+
+    expect(result.warnings).toEqual([]);
+
+    const openapi = JSON.parse(await readFile(path.join(root, "openapi.json"), "utf8"));
+    const uiData = JSON.parse(await readFile(path.join(root, "ui-data.json"), "utf8"));
+    const html = await readFile(path.join(root, "index.html"), "utf8");
+
+    expect(openapi.paths["/users/{id}"]).toBeDefined();
+    expect(uiData.endpoints).toHaveLength(1);
+    expect(html).toContain("/ui-data.json");
+    expect(html).toContain("Copy curl");
+  });
+});

package/tests/resolver.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseDataClassesFromSource,
+  resolveSchemaForType,
+  type KotlinTypeRegistry
+} from "../src/resolver.js";
+
+describe("parseDataClassesFromSource", () => {
+  it("extracts dto properties and nullability", () => {
+    const source = `
+      data class CreateUserRequest(
+        val name: String,
+        val age: Int?,
+        val profile: UserProfile
+      )
+
+      data class UserProfile(
+        val createdAt: Instant
+      )
+    `;
+
+    const registry = parseDataClassesFromSource(source);
+    expect(registry.CreateUserRequest).toBeDefined();
+    expect(registry.CreateUserRequest.properties).toEqual([
+      { name: "name", type: "String", nullable: false },
+      { name: "age", type: "Int?", nullable: true },
+      { name: "profile", type: "UserProfile", nullable: false }
+    ]);
+  });
+
+  it("uses snake_case by default and camelCase for JsonNaming lower camel", () => {
+    const source = `
+      data class DefaultNaming(
+        val firstName: String,
+        val createdAt: Instant
+      )
+
+      @JsonNaming(PropertyNamingStrategies.LowerCamelCaseStrategy::class)
+      data class CamelNaming(
+        val firstName: String,
+        val createdAt: Instant
+      )
+    `;
+
+    const registry = parseDataClassesFromSource(source);
+    const components: Record<string, unknown> = {};
+    resolveSchemaForType("DefaultNaming", registry, components);
+    resolveSchemaForType("CamelNaming", registry, components);
+
+    expect(components.DefaultNaming).toEqual({
+      type: "object",
+      properties: {
+        first_name: { type: "string" },
+        created_at: { type: "string", format: "date-time" }
+      },
+      required: ["first_name", "created_at"]
+    });
+    expect(components.CamelNaming).toEqual({
+      type: "object",
+      properties: {
+        firstName: { type: "string" },
+        createdAt: { type: "string", format: "date-time" }
+      },
+      required: ["firstName", "createdAt"]
+    });
+  });
+});
+
+describe("resolveSchemaForType", () => {
+  it("unwraps wrappers and resolves nested dto schemas", () => {
+    const registry: KotlinTypeRegistry = {
+      UserDto: {
+        name: "UserDto",
+        namingStrategy: "snake_case",
+        properties: [
+          { name: "id", type: "Long", nullable: false },
+          { name: "name", type: "String", nullable: false }
+        ]
+      }
+    };
+
+    const components: Record<string, unknown> = {};
+    const schema = resolveSchemaForType("ResponseEntity<List<UserDto>>", registry, components);
+
+    expect(schema).toEqual({
+      type: "array",
+      items: { $ref: "#/components/schemas/UserDto" }
+    });
+    expect(components.UserDto).toEqual({
+      type: "object",
+      properties: {
+        id: { type: "integer", format: "int64" },
+        name: { type: "string" }
+      },
+      required: ["id", "name"]
+    });
+  });
+});

package/tests/scanner.test.ts

@@ -0,0 +1,138 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseKotlinControllerFile, scanSpringProject } from "../src/scanner.js";
+
+describe("parseKotlinControllerFile", () => {
+  it("extracts controller prefix, mapping method, and request metadata", () => {
+    const source = `
+      package demo
+
+      @RestController
+      @RequestMapping("/api/v1/users")
+      class UserController {
+
+        @GetMapping("/{id}")
+        fun getUser(
+          @PathVariable id: Long,
+          @RequestParam(required = false) includePosts: Boolean?,
+          @RequestHeader("X-Trace-Id") traceId: String
+        ): UserDto {
+          TODO()
+        }
+
+        @PostMapping(path = ["", "/"])
+        fun createUser(@RequestBody body: CreateUserRequest): ResponseEntity<UserDto> {
+          TODO()
+        }
+      }
+    `;
+
+    const endpoints = parseKotlinControllerFile(source, "UserController.kt");
+
+    expect(endpoints).toHaveLength(3);
+    expect(endpoints[0]).toMatchObject({
+      operationName: "getUser",
+      httpMethod: "GET",
+      fullPath: "/api/v1/users/{id}",
+      returnType: "UserDto",
+      pathVariables: [{ name: "id", type: "Long" }],
+      queryParams: [{ name: "include_posts", type: "Boolean?", required: false }],
+      headers: [{ name: "X-Trace-Id", type: "String" }]
+    });
+    expect(endpoints[1]).toMatchObject({
+      operationName: "createUser",
+      httpMethod: "POST",
+      fullPath: "/api/v1/users",
+      requestBody: { type: "CreateUserRequest", required: true },
+      returnType: "ResponseEntity<UserDto>"
+    });
+    expect(endpoints[2]).toMatchObject({
+      operationName: "createUser",
+      httpMethod: "POST",
+      fullPath: "/api/v1/users/"
+    });
+  });
+
+  it("supports RequestMapping value/path arrays and parameter alias keys", () => {
+    const source = `
+      @RestController
+      @RequestMapping(path = ["/v2", "/v2-alt"])
+      class MixedController {
+
+        @RequestMapping(
+          value = ["/items", "/things"],
+          method = [RequestMethod.GET, RequestMethod.POST]
+        )
+        fun list(
+          @PathVariable(name = "item_id") id: Long,
+          @RequestParam(name = "page_no", required = false) page: Int?,
+          @RequestHeader(value = "x-token") token: String
+        ): ItemResponse {
+          TODO()
+        }
+      }
+    `;
+
+    const endpoints = parseKotlinControllerFile(source, "MixedController.kt");
+
+    expect(endpoints).toHaveLength(8);
+    const getPaths = endpoints
+      .filter((e) => e.httpMethod === "GET")
+      .map((e) => e.fullPath)
+      .sort();
+    expect(getPaths).toEqual([
+      "/v2-alt/items",
+      "/v2-alt/things",
+      "/v2/items",
+      "/v2/things"
+    ]);
+
+    expect(endpoints[0].pathVariables[0].name).toBe("item_id");
+    expect(endpoints[0].queryParams[0]).toMatchObject({ name: "page_no", required: false });
+    expect(endpoints[0].headers[0].name).toBe("x-token");
+  });
+});
+
+describe("scanSpringProject", () => {
+  it("scans src/main/kotlin/**/*.kt and skips non-controller files", async () => {
+    const rootPath = path.join(os.tmpdir(), `scanner-${Date.now()}`);
+    const created = await mkdir(rootPath, { recursive: true });
+    const root = created ?? rootPath;
+    const kotlinDir = path.join(root, "src", "main", "kotlin", "demo");
+    await mkdir(kotlinDir, { recursive: true });
+
+    await writeFile(
+      path.join(kotlinDir, "OrderController.kt"),
+      `
+        @RestController
+        @RequestMapping("/orders")
+        class OrderController {
+          @DeleteMapping("/{id}")
+          fun delete(@PathVariable id: Long): Unit = TODO()
+        }
+      `,
+      "utf8"
+    );
+
+    await writeFile(
+      path.join(kotlinDir, "OrderService.kt"),
+      `
+        class OrderService {
+          fun run(): String = "ok"
+        }
+      `,
+      "utf8"
+    );
+
+    const result = await scanSpringProject(root);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      operationName: "delete",
+      httpMethod: "DELETE",
+      fullPath: "/orders/{id}",
+      sourceFile: path.join(kotlinDir, "OrderController.kt")
+    });
+  });
+});