sveltekit-api-gen으로 API 문서 자동화

Source: Dev.to

Introduction

문서는 개발 과정에서 가장 뒤처지기 쉬운 부분입니다. 작성해야 한다는 건 모두 알고 있지만, OpenAPI 사양을 코드와 동기화하는 일은 번거로울 수 있습니다.
SvelteKit으로 백엔드를 구축하고 있다면, sveltekit-api-gen이 여러분을 도와줄 것입니다.

핵심 아이디어는 간단합니다: 엔드포인트 구현 파일을 진실의 원천으로 삼고, 그곳에서 모든 문서를 자동으로 생성합니다.

How It Works

sveltekit-api-gen은 SvelteKit 서버 엔드포인트 파일을 스캔하여 JSDoc @swagger 주석을 직접 파싱함으로써 OpenAPI 3.0 사양을 자동으로 생성합니다. 별도의 YAML 또는 JSON 파일을 관리할 필요 없이 구현 파일에 주석을 달기만 하면 됩니다.

Example

// src/routes/api/users/+server.ts

/**
 * @swagger
 * /api/users:
 *   get:
 *     description: Get all users
 *     responses:
 *       200:
 *         description: A list of users
 */
export async function GET() {
  // ... your logic
}

sveltekit-api-gen은 이러한 주석을 읽어 완전하고 표준에 부합하는 OpenAPI 사양을 만들어 줍니다.

Lightweight Workflow

1. Add @swagger docs as you build endpoints.
2. Generate openapi.json (or openapi.yaml) in CI.
3. Publish it to Swagger UI, Postman, or your internal docs site.
4. Fail CI if generation breaks, catching documentation drift immediately.

Benefits

• Single Source of Truth – Documentation lives right next to your code. Updating the comment updates the spec.
• Automation – No more manual updates to huge JSON files.
• Standard Compliant – Generates OpenAPI 3.0 specs compatible with Swagger UI, Postman, and other tools.

Best Practices

• Be consistent with paths – Ensure the documented path matches your SvelteKit route layout.
• Document error responses – Even a simple 400 and 500 section saves debugging time.
• Keep schemas close – If you’re using Zod or similar, consider mirroring important constraints in your Swagger docs.

Installation

npm install -D sveltekit-openapi-generator
# or
pnpm add -D sveltekit-openapi-generator
# or
bun add -d sveltekit-openapi-generator

Once installed, check the repository README for the exact generate command and output path you prefer (the tool is intentionally configurable).

Repository

https://github.com/Michael-Obele/sveltekit-api-gen

If you found this helpful, please star the repo!