# TOOLING-ITD-005: API Documentation

## CONTEXT

LostHex builds APIs for client projects using Next.js App Router. Clients need API documentation to integrate with our services. Manually writing and maintaining API docs leads to drift—docs say one thing, code does another.

**Current State:** No API documentation in the starter. Health endpoint exists but isn't documented.

**The Challenge:** We need API docs that:

* Stay in sync with actual code behavior
* Provide type safety during development
* Export to GitBook for client access
* Don't require excessive boilerplate

## PROBLEM

How should we generate API documentation for Next.js projects?

## OPTIONS CONSIDERED

1. ✅ **Zod + zod-to-openapi**: Define schemas with Zod, generate OpenAPI spec
2. **next-swagger-doc**: JSDoc comments in route handlers generate OpenAPI
3. **ts-rest**: Contract-first API definition with generated client/server/docs
4. **Manual OpenAPI**: Hand-write `openapi.yaml`, keep in sync manually
5. **Hono/Elysia**: Replace Next.js API routes with framework that has built-in OpenAPI

## REASONING

*Option 1 (Zod + zod-to-openapi):* Zod is already the TypeScript ecosystem standard for runtime validation. Adding `zod-to-openapi` generates OpenAPI specs from the same schemas used for validation—single source of truth. Downsides: extra dependencies (\~50kb), need to learn Zod syntax, OpenAPI metadata (descriptions, examples) lives in `.openapi()` extensions which can drift. But schema drift is far less likely than comment drift.

*Option 2 (next-swagger-doc):* Lower barrier—just add JSDoc comments to existing routes. But comments have no runtime enforcement. Code changes, comments stay stale. Seen this fail at scale.

*Option 3 (ts-rest):* Full contract-first approach with generated everything. Excellent type safety. But heavy setup, opinionated structure, overkill for most LostHex projects. Better for large API-first products.

*Option 4 (Manual OpenAPI):* Simple, no dependencies. But manual sync is a maintenance burden. Guaranteed to drift on any non-trivial project.

*Option 5 (Hono/Elysia):* These frameworks have excellent built-in OpenAPI support. But they replace Next.js API routes entirely. We'd lose Next.js middleware, caching, and ecosystem benefits. Too big a change for documentation alone.

**Why Zod:** Most teams already use or want Zod for validation. Schemas become the source of truth for types, validation, AND documentation. The learning curve is worth it—Zod knowledge transfers across projects and the ecosystem.

## IMPLICATIONS

* Add `zod` and `@asteasolutions/zod-to-openapi` to Next.js package
* CI generates `openapi.json` on push to main
* GitBook CLI publishes spec to GitBook organization
* GitBook renders interactive API documentation for clients
* Define request/response schemas with Zod for each endpoint
* Team learns Zod schema syntax (transferable skill)
* Requires `GITBOOK_TOKEN` secret in GitHub


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://losthex.gitbook.io/losthex-docs/tooling-itds/tooling-itd-005-api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.