Static API Docs Generator from app/api for Swagger/OpenAPI-like tooling

[Acidias]

Goals

1. Automatically map app/api/**/route.ts files to endpoints
2. Detect supported HTTP methods (GET, POST, etc.) from exports
3. Infer request/response types and generate static API schema (OpenAPI/Swagger-compatible)

Non-Goals

1. Introduce runtime decorators or strict typing enforcement
2. Replace validation libraries like Zod or Yup
3. Lock users into OpenAPI specifically (should support similar formats too)

Background

With the new App Router and file-based API design, Next.js makes it easier than ever to build fullstack apps. However, there’s no native or community-supported way to generate even basic static API documentation.

While frameworks like NestJS or FastAPI provide OpenAPI generation out of the box, Next.js developers must manually maintain API docs or use external schemas. But much of the structure is already available: file path = route, exported function = method, and TypeScript types = schema.

Proposal

Introduce an optional static CLI or plugin (npx next-api-docs) that scans the app/api folder, collects exported methods, follows TypeScript types, and outputs a JSON/YAML spec consumable by Swagger UI or similar tools.

Would support OpenAPI but remain agnostic to specific standards.

Happy to contribute or collaborate on an initial proof of concept!