Automate Your API Documentation with sveltekit-api-gen

Source: Dev.to

Introduction

Documentation is often the part of development that gets left behind. We all know we should write it, but keeping an OpenAPI spec in sync with your code can be tedious.
If you are building a backend with SvelteKit, sveltekit-api-gen is here to save the day.

The big idea is simple: treat your endpoint implementation files as the source of truth, and generate everything else from there.

How It Works

sveltekit-api-gen automatically generates OpenAPI 3.0 specifications from your SvelteKit server endpoints by parsing JSDoc @swagger annotations directly in your code. Instead of maintaining a separate YAML or JSON file, you simply annotate the implementation files.

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 scans these comments and builds a complete, compliant OpenAPI specification for you.

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!