@restdocs

Stop writing API docs twice. Test-driven documentation for Next.js - Generate OpenAPI specs, TypeScript types, and interactive Swagger UI directly from your tests.

---

🚨 The Problem: API Documentation Hell

If you're building Next.js APIs for production, you know the pain:

// ❌ THE OLD WAY: Write tests...
it('creates user', async () => {
    const res = await POST(request);
    expect(res.status).toBe(201);
});

// ...then SEPARATELY maintain OpenAPI docs
/**
 * @openapi
 * /api/users:
 *   post:
 *     summary: Create user
 *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               email: {type: string, format: email}
 *               name: {type: string, minLength: 2}
 *     responses:
 *       201:
 *         description: User created
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id: {type: string, format: uuid}
 *                 email: {type: string}
 *                 name: {type: string}
 */

Result?

• ❌ 150+ lines of docs for 10 lines of test code
• ❌ Docs drift within weeks (guaranteed)
• ❌ Maintenance nightmare - update both on every API change
• ❌ No TypeScript types generated from specs

---

✅ The Solution: @restdocs

Write your test once. Get everything else automatically.

// ✅ THE @restdocs WAY: One test, complete documentation
import { api, field } from '@restdocs/core';

it('creates user', async () => {
    const res = await POST(request);

    // 👇 This ONE call generates OpenAPI + TypeScript + Swagger UI
    api.document('POST /api/users', {
        description: 'Create a new user',
        request: {
            email: field.email().required(),
            name: field.string().required().minLength(2).maxLength(50),
        },
        response: {
            id: field.uuid(),
            email: field.email(),
            name: field.string(),
            createdAt: field.datetime(),
        },
        statusCode: 201,
    });

    expect(res.status).toBe(201);
});

After running npm test, you get:

• ✅ openapi.json - Full OpenAPI 3.0 spec
• ✅ types.ts - Auto-generated TypeScript interfaces
• ✅ api.md - Human-readable documentation
• ✅ Swagger UI - Interactive API explorer at /api/__restdocs

70% less code. 100% accuracy. Always in sync.

---

🎯 Why Teams Choose @restdocs

For Next.js 15 App Router Projects

Pain Point	Traditional Approach	@restdocs
API Documentation	Manual OpenAPI YAML/JSON	Auto-generated from tests
Type Safety	Manually sync types with docs	Types generated automatically
Doc Accuracy	Drifts after 2-3 sprints	Always matches code (test-driven)
Developer Experience	Context switch to write docs	Document while testing
Team Onboarding	Read outdated docs → confusion	Interactive Swagger UI + accurate specs
API Contract Validation	Manual or separate tools	Built-in validation against schemas

Real Impact

• 70% less documentation code - One test vs. test + separate docs
• Zero documentation drift - Docs generated from actual API behavior
• 10x faster onboarding - New devs explore APIs via Swagger UI
• Type-safe integration - Frontend teams use generated TypeScript types

---

📦 Quick Start (5 minutes)

1. Install

npm install @restdocs/nextjs --save-dev

2. Configure Next.js

// next.config.ts
import { withRestDocs } from '@restdocs/nextjs/config';

export default withRestDocs({
    restdocs: {
        enabled: process.env.NODE_ENV === 'development',
        path: '/api/__restdocs',
    },
});

3. Configure Jest

// jest.config.js
const nextJest = require('next/jest');
const createJestConfig = nextJest({ dir: './' });

module.exports = createJestConfig({
    reporters: [
        'default',
        [
            '@restdocs/jest/reporter',
            {
                outputDir: './docs/api',
                formats: ['openapi', 'markdown', 'typescript'],
            },
        ],
    ],
});

4. Create Dev UI Route

// app/api/__restdocs/route.ts
import { createDevUIHandler } from '@restdocs/nextjs/dev-ui';

const handler = createDevUIHandler();
export { handler as GET };

5. Document Your First API

// __tests__/api/users.test.ts
import { api, field } from '@restdocs/core';
import { POST } from '@/app/api/users/route';

it('creates user', async () => {
    const res = await POST(request);

    api.document('POST /api/users', {
        description: 'Create a new user',
        request: {
            email: field.email().required(),
            name: field.string().required().minLength(2),
        },
        response: {
            id: field.uuid(),
            email: field.email(),
            name: field.string(),
        },
        statusCode: 201,
    });

    expect(res.status).toBe(201);
});

6. Run Tests & View Docs

# Generate documentation
npm test

# Start dev server
npm run dev

# Open Swagger UI
open http://localhost:3000/api/__restdocs

---

🔥 Key Features

Fluent Schema DSL

field
    .string()
    .required()
    .minLength(2)
    .maxLength(50)
    .pattern(/^[A-Z]/)
    .description('User name')
    .example('John Doe');

field.email().required();
field.uuid();
field.datetime();
field.integer().min(18).max(120);
field.array(field.string()).uniqueItems();
field.object({
    name: field.string(),
    age: field.integer().optional(),
});

Automatic Type Inference

const requestBody = {
    email: 'user@example.com',
    name: 'John Doe',
};

api.document('POST /api/users', {
    request: api.infer(requestBody, { required: ['email', 'name'] }),
    response: api.infer(response.body),
});

Built-in Validation

// Validate response against documented schema
api.validate(response.body).against('POST /api/users', 201);
// Throws descriptive error if validation fails

Multiple Output Formats

After running tests, get:

• openapi.json - OpenAPI 3.0 specification
• api.md - Markdown documentation
• types.ts - TypeScript type definitions
• Dev UI - Interactive Swagger UI (Next.js only)

---

🧪 Experimental Status & Transparency

@restdocs is in active beta (v0.3.0). This means:

✅ What's Stable

• Core DSL API and field builders
• Jest integration and test reporter
• OpenAPI 3.0 generation
• Next.js 15 App Router support
• TypeScript type generation
• 247 tests passing (100% coverage)

⚠️ What's Experimental

• Performance at scale - Tested with ~50 endpoints, not 500+
• Complex schemas - Nested objects work, but edge cases may exist
• Framework support - Next.js is solid, others (Express/Fastify) are lighter
• Production readiness - Use in dev/staging first, production at your own risk

🔮 What's Coming (Roadmap)

• Vitest native support (currently uses Jest API)
• Advanced schema features (discriminated unions, recursive types)
• Performance optimization for large APIs (100+ endpoints)
• Plugin ecosystem for custom generators
• Fastify/Express deep integration

💡 Perfect For

• ✅ Greenfield Next.js projects building APIs
• ✅ Teams tired of doc-test maintenance overhead
• ✅ Developers who want to experiment with test-driven docs
• ✅ Projects where API contract accuracy is critical

🚫 Not Ready For (Yet)

• ❌ Mission-critical APIs without fallback documentation
• ❌ Large-scale production deployments (test in staging first)
• ❌ Complex OpenAPI 3.1 features (allOf/oneOf/discriminators)

We're being transparent: This tool will save you time, but it's young. Use it, break it, and help us make it production-ready. Star the repo, report issues, and join the journey.

---

🏗️ Project Structure

@restdocs/
├── packages/
│   ├── restdocs/      # @restdocs/core - Core DSL engine
│   ├── generators/    # @restdocs/generators - Output generators
│   ├── jest/          # @restdocs/jest - Jest integration
│   └── nextjs/        # @restdocs/nextjs - Next.js integration
└── examples/
    ├── express-jest/       # Express + Jest example
    └── nextjs-app-router/  # Next.js 15 App Router example

---

📖 Full Documentation

Field Types

Strings

field.string().required().minLength(2).maxLength(50);
field.email(); // String with email format
field.uuid(); // String with UUID format
field.uri(); // String with URI format
field.datetime(); // ISO 8601 datetime
field.date(); // ISO 8601 date

Numbers

field.number().min(0).max(100);
field.integer().multipleOf(5);

Complex Types

field.boolean().default(true);
field.object({
    name: field.string().required(),
    age: field.integer().optional(),
});
field.array(field.string()).minItems(1).maxItems(10);

API Functions

// Document an endpoint
api.document('POST /api/users', { ... });

// Auto-infer schema from data
api.infer(data, { required: ['email'] });

// Validate response against schema
api.validate(response.body).against('POST /api/users', 201);

---

🎓 Learn by Example

Check out the Next.js 15 example project with:

• JWT authentication (register + login)
• Users & Posts CRUD APIs
• 19 comprehensive tests
• Full OpenAPI documentation
• TypeScript types generated

---

🤝 Contributing

@restdocs is experimental - we need your feedback!

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Start a discussion
• 🚀 Want to contribute? See CONTRIBUTING.md

---

🙏 Inspired By

• Spring REST Docs - Test-driven documentation for Spring
• Zod - TypeScript-first schema validation

---

📝 License

MIT © Jae Song Choi

---

📮 Get Help

• 📫 GitHub Issues
• 💬 GitHub Discussions

---

Built with ❤️ for Next.js teams who hate writing docs twice.

⭐ Star this repo if you believe API docs should just work.