Stop Writing OpenAPI Specs by Hand: A Better Way

Writing OpenAPI specifications manually is one of the most tedious tasks in backend development. Here's how to generate them automatically and keep them accurate.

👤 AutoDocAPI Team
api-documentation openapi developer-tools automation technical-writing

Every backend developer eventually faces the same situation: you build a nice API, you ship it, and then someone asks for documentation. Or worse — you inherit an API from a colleague and have to document it from scratch.

Writing an OpenAPI specification by hand is painful:

  • You need to know the YAML/JSON syntax
  • You have to document every field, every response code, every error
  • It gets out of sync with the actual API almost immediately
  • AI tools generate plausible-looking but often inaccurate specs

This article looks at the problem and the approaches that actually work.

Why OpenAPI matters

An OpenAPI specification is more than documentation. It’s a contract. With a valid .yaml or .json spec file, you can:

  • Auto-generate a Swagger UI or Redoc documentation page
  • Import into Postman with all endpoints pre-configured
  • Generate client SDKs in any language
  • Run contract testing to catch regressions automatically
  • Enable mock servers so front-end developers don’t need the real API

The spec is the source of truth. Everything else is generated from it.

The traditional approaches (and why they fall short)

Approach 1: Write YAML by hand

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

This works, but it’s slow and error-prone. A medium-complexity API with 20 endpoints can easily take 20–40 hours to document properly.

Approach 2: Code-first with annotations

Frameworks like SpringDoc (Java), FastAPI (Python), or NestJS can generate specs from code annotations:

@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int):
    ...

This is great when you’re starting from scratch, but doesn’t help with existing APIs or third-party services.

Approach 3: Capture traffic with a proxy

Tools like Stoplight or Postman’s collection runner can capture HTTP traffic and generate specs from real requests. Good in theory, but:

  • Requires running the API and hitting every endpoint
  • You only document the responses you’ve actually received
  • Field descriptions are still empty

The better approach: AI-assisted generation from examples

The most practical approach for most teams is:

  1. Paste your API endpoint URL and a sample JSON response
  2. Let AI fill in the descriptions for every field
  3. Review and edit anything that needs adjustment
  4. Export to YAML, JSON, or Postman

This is what AutoDocAPI does. Let us show you what the workflow looks like.

AutoDocAPI workflow

Step 1: Enter the endpoint

You provide:

  • The HTTP method (GET, POST, etc.)
  • The URL path (e.g., /api/v1/users/{id})
  • A sample JSON response

Example input:

{
  "id": 42,
  "email": "[email protected]",
  "full_name": "John Doe",
  "created_at": "2026-01-15T09:23:00Z",
  "is_active": true,
  "role": "admin",
  "preferences": {
    "theme": "dark",
    "language": "en"
  }
}

Step 2: Review AI-generated descriptions

The tool automatically generates:

  • Field names and data types from the JSON structure
  • Descriptions for each field using AI (e.g., “The Unix timestamp indicating when the user account was created”)
  • Example values from your actual sample

You can edit any field inline before exporting.

Step 3: Export

Click Export to get:

  • OpenAPI 3.0 YAML
  • OpenAPI 3.0 JSON
  • Postman Collection v2.1

The generated spec is valid and can be immediately imported into Swagger UI, Postman, or any OpenAPI-compatible tool.

The quality of AI-generated descriptions

One common concern: will the descriptions actually be useful, or will they be generic filler?

Here’s a real comparison for the same field:

Generic (bad):

created_at: The creation timestamp.

AI-generated (good):

created_at: ISO 8601 timestamp indicating when the user account was created in the system. Format: YYYY-MM-DDTHH:mm:ssZ.

The difference matters for developers who are consuming your API for the first time.

When to use each approach

ScenarioRecommended approach
New API built with FastAPI/NestJSCode-first annotations
Existing API, no docs yetAI-assisted generation from examples
Third-party API you need to documentAI-assisted generation from examples
Large team with API governanceDesign-first with Stoplight/Swagger Editor
Quick one-off documentationAI-assisted generation from examples

For most solo developers and small teams, the AI-assisted approach gives the best time-to-quality ratio.

Keeping docs in sync

The hardest part of API documentation isn’t writing it — it’s keeping it current. A few practical strategies:

  1. CI/CD check: Add a step to your pipeline that validates the spec against the running API
  2. Code review requirement: Make spec updates a required part of PRs that change API contracts
  3. Regenerate on change: When a response structure changes, paste the new JSON and regenerate just that endpoint

The goal isn’t a perfect automated system — it’s a low-friction process that developers will actually follow.

Try it yourself

AutoDocAPI’s Starter plan is free and gives you up to 10 API requests to generate specifications. No credit card required — just request access and start generating.

Request free access →

← Back to blog