Generating OpenAPI Specifications with AI

🔄 Quick Recall: In the previous lesson, you built API design patterns — naming conventions, resource modeling, and response structure standards. Now you’ll turn those patterns into machine-readable OpenAPI specifications using AI as your spec writer.

OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. A well-written OpenAPI spec is simultaneously documentation for humans, a contract for consumers, a source for code generation, and a basis for automated testing. The problem: writing OpenAPI YAML by hand is tedious enough that most teams skip it or let it go stale. AI makes spec generation fast enough that design-first becomes the practical default.

Generating Specs from Requirements

AI prompt for OpenAPI spec generation:

Generate a complete OpenAPI 3.1 specification for the following API. Domain: [DESCRIBE YOUR API — e.g., a task management system with users, projects, tasks, and comments]. Requirements: [LIST THE KEY OPERATIONS — CRUD for each resource, search/filter capabilities, relationships between resources]. Style: [YOUR CONVENTIONS — e.g., camelCase fields, cursor-based pagination, envelope response format, ISO 8601 dates]. Generate the full spec with: (1) info section with title, description, version, and contact, (2) paths for all endpoints with request/response schemas, (3) component schemas for all resources with field descriptions and validation rules, (4) example values for every request and response, (5) security scheme definitions, (6) error response schemas for 400, 401, 403, 404, and 500. Output as valid OpenAPI 3.1 YAML.

What to specify vs. what AI decides:

Iterative Spec Refinement

AI prompt for spec review and refinement:

Review this OpenAPI specification for completeness and best practices. [PASTE SPEC OR DESCRIBE WHAT WAS GENERATED]. Check for: (1) Missing endpoints — are there CRUD operations that should exist but don’t? (2) Missing response codes — does each endpoint handle 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), and 500 (server error)? (3) Missing query parameters — should list endpoints support filtering, sorting, or searching? (4) Schema completeness — does each resource have created_at, updated_at? Are relationships properly defined? (5) Example quality — are examples realistic and consistent across related endpoints? (6) Security — is authentication required on appropriate endpoints? List all findings with suggested fixes.

✅ Quick Check: AI generates a spec for your user endpoint. The GET /users/:id response includes the password hash field. Is this a problem? (Answer: Yes — this is a critical security issue. Password hashes should never be returned in API responses, even in specs. The schema should mark password-related fields as writeOnly: true so they only appear in request schemas, not responses. AI occasionally includes all database fields in responses unless you specify otherwise. Always review: “Which fields should a consumer NEVER see?”)

Schema Component Design

AI prompt for reusable schema components:

Design reusable schema components for my API. Domain: [YOUR DOMAIN]. Create: (1) Base schemas — a standard resource base with id, created_at, updated_at that other schemas extend, (2) Request vs. response schemas — separate CreateUserRequest (fields you send) from UserResponse (fields you get back, including read-only fields), (3) Pagination schema — a reusable PaginatedResponse component with cursor, has_more, and total fields, (4) Error schema — a standard error response component with code, message, details, and request_id, (5) Common types — Address, Money, DateRange, PhoneNumber, etc. that multiple resources share. Use OpenAPI’s $ref for all shared components to keep the spec DRY.

Common schema patterns:

Spec-to-Code Workflow

AI prompt for implementation scaffolding:

Given this OpenAPI specification [PASTE OR REFERENCE SPEC], generate implementation scaffolding in [LANGUAGE/FRAMEWORK — e.g., Express.js, FastAPI, Go/Gin]. Create: (1) route definitions matching every path in the spec, (2) request validation middleware using the spec’s schema constraints, (3) response type definitions matching the spec’s schemas, (4) stub handler functions with correct signatures (request params, body, response type), (5) error handling middleware that returns errors in the spec’s error format. The generated code should be a compilable starting point that returns mock data matching the spec’s examples, ready for business logic to be added.

Key Takeaways

• AI generates complete OpenAPI 3.x specs from plain English descriptions in 15-20 minutes — eliminating the tedium that causes teams to skip the design phase and go straight to coding
• Always review AI-generated specs for business logic decisions, not just syntax: which fields are required, what should be write-only (passwords), what should be read-only (timestamps), and which fields shouldn’t exist in the API at all
• Response examples are one of the highest-value additions to any spec — they serve as documentation, contract test fixtures, and mock server data, and AI generates realistic examples automatically
• Separate request and response schemas (CreateUserRequest vs. UserResponse) because what you send to create a resource is almost never identical to what you get back — AI handles this distinction cleanly with reusable components
• The spec-to-code workflow (requirements → AI-generated spec → review → scaffolded code) is faster than code-first AND produces better results because design decisions happen before implementation commits you to them

Up Next

In the next lesson, you’ll build automated documentation systems — turning your OpenAPI specs into beautiful, interactive developer documentation that stays synchronized with your code.