Checklist

You have learned how to describe endpoints, document parameters, define schemas, generate specs from Zod, serve interactive docs, generate typed clients, and set up versioned specs. That is a lot of ground. Here is a checklist you can use on any API project to make sure nothing is missed.

Route definitions

• Every route has request schemas for params, query, and/or body
• Every route has response schemas mapping status codes to Zod types
• Response schemas include success cases (200, 201) and error cases (400, 401, 403, 404)
• Status codes like 204 are included for delete operations

OpenAPI config

• info with title, version, and description
• servers for each environment (dev, staging, production)
• tags for endpoint grouping with descriptions
• securitySchemes with Bearer auth (or your auth method)
• security applied globally

Schemas

• Separate Zod schemas for request (CreateBookSchema) and response (BookSchema)
• ErrorSchema and ValidationErrorSchema for error responses
• Pagination schema for list endpoints (BookListSchema)
• All schemas defined in Zod (single source of truth)

Human-friendly

• Field descriptions on every non-obvious field using .describe()
• Tag descriptions with auth notes and resource overview
• Error descriptions explaining what each error code means

Serving and consuming

• api.spec(route) added to routes for /openapi.json
• api.docs(route) added to routes for /docs
• Client types generated from spec with openapi-typescript
• Versioned specs if running multiple API versions

Common mistakes

Missing response schemas. Defining request schemas but not response schemas on your routes. Without response schemas, the generated spec only says “200 OK” with no body shape.

Only documenting success. Adding response: { 200: BookSchema } but forgetting about 400, 401, and 404. Clients need to know every possible response so they can handle errors.

Forgetting to pass routes to openapi(). Adding a new route to the app but not including it in the array passed to openapi(). The endpoint works, but the docs do not know about it.

Hand-written schemas. Writing OpenAPI schemas by hand instead of using Zod. This defeats the entire purpose. Define shapes in Zod and let @hectoday/openapi generate the spec.

Missing descriptions. Types tell clients the structure. Descriptions tell them what things mean. A field like authorId: { type: "string", format: "uuid" } without a description leaves clients guessing where to get a valid author ID.