AI Prompt for OpenAPI Specs

Generate valid OpenAPI specs with this AI prompt: complete paths, reusable schemas, realistic examples, auth schemes, and a validation checklist.

The prompt

Role: You are an API specification expert who writes flawless OpenAPI specifications.

Context: OpenAPI version: [VERSION: 3.0 / 3.1]. API title: [API_TITLE].

Endpoints:
[ENDPOINT_LIST with methods, paths, parameters, request/response shapes]

Auth: [AUTH_SCHEME].

Task: 1) Write the complete OpenAPI [VERSION] spec in YAML: info, servers, paths with operations, parameters, request bodies, responses (success + errors), and reusable schemas in components. 2) Include realistic examples for every schema. 3) Define the security scheme and apply it. 4) Validate mentally: every $ref resolves, every response has a schema, no duplicated schema definitions.

Format: The full YAML spec in a code block, followed by a short validation checklist of what you checked.

Ask the AI to also emit the Markdown documentation derived from the spec, so the machine-readable contract and the human-readable docs can never disagree.

Constraints: Valid [VERSION] syntax — no invented fields. Reuse schemas via components instead of duplicating. Every endpoint needs at least the 200 and one error response documented.

Variables to fill in

Replace each [variable] in the prompt with your own details:

[VERSION] [API_TITLE] [ENDPOINT_LIST] [AUTH_SCHEME]

Example input

API=task management API, ENDPOINTS=CRUD for tasks + assign + complete, AUTH=Bearer JWT, VERSION=1.0.0, STYLE=OpenAPI 3.1

How to use this prompt

List every endpoint with its fields before generating — the spec is only as complete as your endpoint inventory. Specify the OpenAPI version your tooling supports.

Tips for the best results

Paste the spec into Swagger Editor to validate — ask the AI to fix any validation errors.
Ask for the spec and the docs in one go: OpenAPI first, then human-readable Markdown from it.
Keep schemas in components; duplication is where specs rot.