Root Structure
- openapiVersion (3.0.x)
- infoAPI metadata
- serversServer URLs
- pathsAPI endpoints
- componentsReusable schemas
- securityAuth requirements
- tagsGrouping tags
HTTP Methods
- getRead resource
- postCreate resource
- putReplace resource
- patchUpdate resource
- deleteDelete resource
Parameter Locations
- pathURL path params
- queryQuery string
- headerHTTP headers
- cookieCookie values
Data Types
- stringText values
- integerWhole numbers
- numberFloating point
- booleantrue/false
- arrayList of items
- objectKey-value pairs
Basic Spec Structure
openapi: "3.0.3"
info:
title: My API
version: "1.0.0"
description: API Description
contact:
email: api@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
Path Definition
paths:
/users/{userId}:
get:
summary: Get user by ID
operationId: getUserById
tags:
- Users
parameters:
- name: userId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
Schema Definitions
components:
schemas:
User:
type: object
required:
- id
- email
properties:
id:
type: integer
format: int64
email:
type: string
format: email
name:
type: string
maxLength: 100
status:
type: string
enum: [active, inactive, pending]
Security Schemes
- apiKeyAPI key auth
- httpBasic/Bearer
- oauth2OAuth 2.0
- openIdConnectOIDC
Response Codes
- 200OK
- 201Created
- 400Bad Request
- 401Unauthorized
- 404Not Found
- 500Server Error
Security Configuration
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
# Apply globally
security:
- bearerAuth: []
String Formats
- dateYYYY-MM-DD
- date-timeISO 8601
- emailEmail format
- uriURI format
- uuidUUID format
- passwordHidden in UI
Schema Keywords
- $refReference
- allOfCombine schemas
- oneOfOne of schemas
- anyOfAny of schemas
- nullableAllow null