OpenAPI · APIsintermediate
OpenAPI 3.1 Specification (Starter)
A minimal but complete OpenAPI 3.1 document with one CRUD resource, reusable schemas and an API-key security scheme — a clean base for any REST API.
openapiswaggerrestapischemacontract
Preview
{
"openapi": "3.1.0",
"info": {
"title": "Items API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/items": {
"get": {
"operationId": "listItems",
"summary": "List items",
"responses": {
"200": {
"description": "A list of items",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Item"
}
}
}
}
}
}
},
"post": {
"operationId": "createItem",
"summary": "Create an item",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewItem"
}
}
}
},
"responses": {
"201": {
"description": "Created"
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key"
}
},
"schemas": {
"Item": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
},
"NewItem": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}AI actions
Documentation
Purpose
Define the contract for a small REST API — paths, request/response schemas, and security — in a single OpenAPI 3.1 document.
When to use
Starting a new API, generating client SDKs or server stubs, or documenting an existing service contract-first.
Required fields
- openapi — the spec version ("3.1.0")
- info — title and version of the API
- paths — the endpoints and their operations
Optional fields
- components.schemas — reusable data models
- components.securitySchemes — auth definitions
- servers — base URLs per environment
Best practices
- Define schemas once under components and $ref them everywhere.
- Give every operation an operationId for codegen.
- Document error responses (4xx/5xx), not just the happy path.
Security considerations
- Declare securitySchemes and apply them with a global or per-op security block.
- Never embed real API keys or tokens in examples.