NeuralBlitz What I do
- Design OpenAPI specifications
- Create API documentation
- Define schemas and data models
- Document authentication
- Handle pagination and filtering
- Use advanced OpenAPI features
- Generate client SDKs
- Test with OpenAPI
When to use me
When creating API specifications or OpenAPI documentation.
OpenAPI Structure
openapi: 3.0.3
info:
title: Pet Store API
description: |
A sample API for managing pets.
## Features
- List pets
- Add new pets
- Update pet information
- Place orders
## Authentication
All endpoints require Bearer token authentication.
version: 1.0.0
contact:
name: API Support
email: support@example.com
url: https://example.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.example.com/v1
description: Production server
- url: https://staging-api.example.com/v1
description: Staging server
- url: http://localhost:8000/api/v1
description: Local development
tags:
- name: Pets
description: Pet management operations
- name: Store
description: Store operations
- name: Users
description: User management
Paths and Operations
paths:
/pets:
get:
summary: List all pets
description: Returns a paginated list of pets
tags:
- Pets
operationId: listPets
parameters:
- name: status
in: query
description: Filter by pet status
schema:
type: string
enum:
- available
- pending
- sold
- name: limit
in: query
description: Maximum number of pets to return
schema:
type: integer
default: 20
minimum: 1
maximum: 100
- name: offset
in: query
description: Number of pets to skip
schema:
type: integer
default: 0
minimum: 0
responses:
'200':
description: A list of pets
content:
application/json:
schema:
$ref: '#/components/schemas/PetListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
post:
summary: Create a new pet
description: Add a new pet to the store
tags:
- Pets
operationId: createPet
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePetRequest'
responses:
'201':
description: Pet created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
Components and Schemas
components:
schemas:
Pet:
type: object
required:
- id
- name
- status
properties:
id:
type: string
format: uuid
example: "123e4567-e89b-12d3-a456-426614174000"
name:
type: string
minLength: 1
maxLength: 100
example: "Fluffy"
status:
type: string
enum:
- available
- pending
- sold
example: "available"
category:
$ref: '#/components/schemas/Category'
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
photoUrls:
type: array
items:
type: string
format: uri
maxItems: 10
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
CreatePetRequest:
type: object
required:
- name
- status
properties:
name:
type: string
minLength: 1
maxLength: 100
status:
type: string
enum:
- available
- pending
- sold
categoryId:
type: integer
format: int64
tags:
type: array
items:
type: string
photoUrls:
type: array
items:
type: string
format: uri
maxItems: 10
PetListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Pet'
pagination:
$ref: '#/components/schemas/Pagination'
meta:
type: object
properties:
requestId:
type: string
timestamp:
type: string
format: date-time
Pagination:
type: object
properties:
total:
type: integer
format: int64
limit:
type: integer
offset:
type: integer
hasMore:
type: boolean
Authentication
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token authentication
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OAuth2Password:
type: oauth2
flows:
password:
tokenUrl: /api/v1/auth/token
scopes:
read: Read access
write: Write access
security:
- BearerAuth: []
- ApiKeyAuth: []
Advanced Features
# Callbacks
paths:
/orders:
post:
summary: Create an order
callbacks:
orderCompleted:
'$ref': '#/components/callbacks/OrderCompleted'
orderShipped:
'$ref': '#/components/callbacks/OrderShipped'
callbacks:
OrderCompleted:
'{$request.body#/callbackUrl}':
post:
requestBody:
description: Order completed callback
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCallback'
responses:
'200':
description: Callback received successfully
# Links
paths:
/users/{userId}:
get:
summary: Get user by ID
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
links:
userOrders:
operationId: getUserOrders
parameters:
userId: '$request.path.userId'
# Webhooks
webhooks:
newOrder:
post:
summary: Receive new order notifications
operationId: newOrderWebhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
responses:
'200':
description: Webhook received
Documentation Best Practices
1. Write clear summaries
- One-line description
- What the endpoint does
2. Provide detailed descriptions
- Explain behavior
- Document edge cases
3. Use proper examples
- Request examples
- Response examples
- Error examples
4. Document all parameters
- Required vs optional
- Valid values
- Default values
5. Define error responses
- Common errors
- Error codes
- Error messages
6. Use tags to organize
- Group by resource
- Group by functionality
7. Keep it up to date
- Update on code changes
- Version documentation
8. Add getting started
- Authentication guide
- Base URL
- Rate limits
Code Generation
# Generate Python client
openapi-generator generate \
-i openapi.yaml \
-g python \
-o ./clients/python \
--additional-properties=pythonLibraryName=petshop
# Generate TypeScript client
openapi-generator generate \
-i openapi.yaml \
-g typescript-axios \
-o ./clients/typescript
# Generate Go server
openapi-generator generate \
-i openapi.yaml \
-g go-gin-server \
-o ./server/go
# Generate Postman collection
openapi-generator generate \
-i openapi.yaml \
-g postman-collection \
-o ./docs/postman.json
Validation with OpenAPI
from openapi_spec_validator import validate
from openapi_spec_validator.versions import consts as validator_versions
def validate_openapi_spec(spec_path: str) -> bool:
"""Validate OpenAPI specification file."""
with open(spec_path, 'r') as f:
spec_dict = yaml.safe_load(f)
try:
validate(spec_dict)
return True
except Exception as e:
print(f"Validation error: {e}")
return False
def check_coverage(spec: dict) -> dict:
"""Check API coverage against requirements."""
paths = spec.get('paths', {})
required_endpoints = [
'/users',
'/users/{id}',
'/pets',
'/pets/{id}',
]
existing = []
missing = []
for endpoint in required_endpoints:
if endpoint in paths:
existing.append(endpoint)
else:
missing.append(endpoint)
return {
'existing': existing,
'missing': missing,
'coverage': len(existing) / len(required_endpoints),
}