OpenAPI Spec from Scratch: A Developer's Guide to API-First Design

API-first design means defining your API specification before writing any implementation code. Instead of building endpoints and then documenting them, you write the OpenAPI spec first and use it as the contract between frontend and backend teams — and between you and your AI coding agents.

This approach has always made sense, but it matters more now that AI coding agents are writing the implementation. An AI agent with a clear OpenAPI spec generates correct routes, validation, and type definitions on the first try. Without one, it guesses at endpoint structures and invents response formats.

What is an OpenAPI Specification?

OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. It is a YAML or JSON document that defines every endpoint, parameter, request body, response schema, and authentication method in a structured, machine-readable format.

An OpenAPI spec serves multiple purposes: it is documentation for human developers, a contract for frontend/backend integration, input for code generators and SDK builders, test scaffolding for API validation tools, and a blueprint for AI coding agents.

Structure of an OpenAPI 3.0 Spec

Every OpenAPI 3.0 spec has these top-level sections: info (API name, version, description), servers (base URLs for different environments), paths (the endpoints — GET /users, POST /tasks, etc.), components (reusable schemas, security schemes, parameters), and security (authentication requirements).

Best Practices for API-First Design

Use consistent naming: Pick a convention (camelCase or snake_case for fields, plural nouns for collections) and stick with it everywhere. Inconsistent naming is the most common issue in generated APIs.

Define error responses: Every endpoint should specify error responses, not just the happy path. Include 400 (validation), 401 (unauthenticated), 403 (forbidden), 404 (not found), and 500 (server error) with consistent error schema.

Use components for reuse: Define schemas in the components section and reference them with $ref. This keeps your spec DRY and ensures the same model is used consistently across endpoints.

Include examples: Add example values for request bodies and response objects. These help developers understand the expected data shapes and are used by mock servers for testing.

Using OpenAPI Specs with AI Coding Agents

AI coding agents like Claude Code and Cursor work dramatically better when given an OpenAPI spec. Instead of prompting "create a tasks API with CRUD operations," you point the agent at a spec that defines exact endpoint paths, request validation schemas, response shapes, and error formats. The agent implements exactly what the spec says, with correct types and validation.

Store your OpenAPI spec in your repository (typically at docs/openapi.yaml or specs/api.yaml) and reference it in your CLAUDE.md so the agent knows where to find it.

Generate an OpenAPI Spec Automatically

Writing an OpenAPI spec from scratch is tedious, especially for complex APIs. Keeborg generates complete OpenAPI 3.0 specifications from plain English descriptions. Describe your app, and Keeborg produces endpoints, request/response schemas, authentication, error handling, and pagination — all consistent with the PRD and database schema it generates alongside.

The generated spec is ready to use with Swagger UI for documentation, code generators for SDK creation, and AI coding agents for implementation. Try it free at keeborg.com.