How to Prompt AI to Write an OpenAPI Spec

To get a good OpenAPI spec out of an AI model, give it your real endpoints, request and response examples, and the OpenAPI version you want, then ask for YAML and nothing else. After that, check the output against the format's structural rules before you trust it. The model is good at the boilerplate. You are responsible for the facts.

An OpenAPI description is the file that tells people and tools what your API can do. It is worth having: once it exists, other tools can generate documentation, client code, and test servers from it, and your AI coding agent can read it instead of guessing at your routes.

What an OpenAPI description is

The OpenAPI introduction calls the OpenAPI Specification a vendor-neutral description format for HTTP-based remote APIs, and a machine-readable specification of an API. It says tooling can generate human-readable documentation, boilerplate client and server code, and mock servers from the description.

Nothing in it is magic. It is a structured file, usually YAML, which is why knowing what a YAML file is helps.

The skeleton the model must get right

Per the structure page, only two top-level fields are mandatory: openapi, the version string such as 3.1.0, and info, which must include a title and a version. At least one of paths, components, or webhooks is also required. The smallest valid example from that page:

openapi: 3.1.0
info:
  title: A minimal OpenAPI Description
  version: 0.0.1
paths: {} # No endpoints defined

The paths field describes the endpoints of the API, including their parameters and all possible server responses. That is where most of your content, and most of the model's mistakes, will live.

What to give the model

Models invent endpoints when you describe an API in prose. Give them evidence instead:

• The actual route list. Paste it from your router file or the output of your framework's route listing.

• One real request and one real response per endpoint, as JSON.

• Authentication details: header name and scheme, with no real keys.

• The error responses you actually return.

• The version you want. Say 3.1.0 explicitly.

Never paste secrets. Replace real tokens with placeholders before you send anything.

A prompt you can reuse

Write an OpenAPI 3.1.0 description in YAML for the API below.

Rules:
- Use only the routes I list. Do not add endpoints.
- Use only the fields that appear in my example payloads.
- Put reusable shapes under components, and reference them.
- If something is unclear, write "TODO: ask" in a description field instead of guessing.
- Output only YAML, no commentary.

Routes:
<paste routes>

Example request and response for each route:
<paste JSON examples>

Authentication: bearer token in the Authorization header.

The "TODO: ask" rule is the most useful line. It turns silent guesses into visible gaps you can fix. For more on getting structured output from a model, see how to get JSON output from AI.

How to check what comes back

Do not skim and publish. Work through this list.

1. Required fields. Confirm openapi and info with title and version are present, plus paths or components.

2. Every route exists. Compare the paths in the spec with your real route list. Delete anything invented.

3. Every field exists. Compare each schema with a real response. Models love to add plausible fields like createdAt that your API does not return.

4. Responses are complete. Check that error responses are described, not just the success case.

5. No secrets. Search the file for tokens and keys.

6. Run it through a validator or a doc generator. If it fails to load, the structure is wrong. The OpenAPI site lists tools at tools.openapis.org.

Step 3 is the one that matters. A spec that looks complete but describes fields your API never returns is worse than no spec, because people will build against it.

Where the spec goes next

Once it is accurate, put it in your repository and point your coding agent at it. Our post on giving an AI coding agent your API docs covers how. If you are weighing REST against newer agent protocols, MCP versus REST API for AI agents compares them, and what an API is covers the basics. More recipes live in the prompt engineering guide.

Frequently asked questions

Can ChatGPT or Claude write an OpenAPI spec?

Yes, they can draft one from your routes and example payloads. Treat the draft as a starting point and check every route and field against your real API.

What are the required fields in an OpenAPI file?

The openapi version string and an info object with title and version, plus at least one of paths, components, or webhooks.

Should the spec be YAML or JSON?

Either can describe an API. YAML is easier to read and edit by hand, which is why most examples use it.

How do I stop the AI inventing endpoints?

List the routes yourself, tell it to use only those, and give it a way to flag unknowns, such as writing "TODO: ask" instead of guessing.