Swagger/OpenAPI Guide
Basic to Advanced with Live Examples and Developer Tips
Introduction
Swagger/OpenAPI lets you define RESTful APIs in a machine-readable format, helping with documentation, testing, and SDK generation.
Tip: OpenAPI 3.x is recommended for modern features and better tool support.
Setup & Installation
Node.js Example
# Install Swagger UI
$ npm install swagger-ui-express swagger-jsdoc
$ npm install swagger-ui-express swagger-jsdoc
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
const swaggerJsdoc = require('swagger-jsdoc');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
Basic YAML/JSON Examples
Basic API Definition
openapi: 3.0.3
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: List of users
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: List of users
{
"openapi": "3.0.3",
"info": { "title": "Sample API", "version": "1.0.0" },
"paths": {
"/users": { "get": {
"summary": "Get all users",
"responses": { "200": { "description": "List of users" } }
} } }
}
"openapi": "3.0.3",
"info": { "title": "Sample API", "version": "1.0.0" },
"paths": {
"/users": { "get": {
"summary": "Get all users",
"responses": { "200": { "description": "List of users" } }
} } }
}
Intermediate Features
Intermediate Authentication
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
security:
- ApiKeyAuth: []
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
security:
- ApiKeyAuth: []
Advanced Techniques
Advanced Reusable Components
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
Live Swagger UI
Pro Tips & Troubleshooting
Pro Tips
- Use tags to organize endpoints.
- Provide examples for request/response bodies.
- Validate YAML/JSON before deployment.
- Enable deepLinking in Swagger UI for better navigation.
Swagger Across Cloud Platforms
Advanced Cloud Integration
Swagger/OpenAPI is platform-independent, but each cloud provider has its own way of integrating and deploying APIs:
| Platform | Hosting | Deployment | Authentication | Monitoring | SDK Generation |
|---|---|---|---|---|---|
| AWS | API Gateway, Lambda | aws apigateway import-rest-api --body file.json |
IAM roles, API keys, Cognito | CloudWatch | Auto SDKs via CLI/Console |
| GCP | Cloud Endpoints | gcloud endpoints services deploy openapi.yaml |
Service Accounts, API keys, OAuth2 | Stackdriver Logging | Auto SDKs via Endpoints |
| Azure | API Management (APIM) | az apim api import --resource-group RG --service-name APIName --path /api --specification-format OpenApi |
OAuth2, Managed Identity | Application Insights | SDKs via APIM portal |
Note: Keep a core OpenAPI spec universal and use cloud-specific extensions only when deploying to a specific platform.
Example: AWS Vendor Extension
paths:
/users:
get:
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:region:lambda:path/2015-03-31/functions/arn:aws:lambda:region:account-id:function:myFunction/invocations
httpMethod: POST
type: aws_proxy
/users:
get:
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:region:lambda:path/2015-03-31/functions/arn:aws:lambda:region:account-id:function:myFunction/invocations
httpMethod: POST
type: aws_proxy
Real-World Examples
Pro Developer Use Cases
# Swagger CLI to validate YAML
$ swagger-cli validate openapi.yaml
$ swagger-cli validate openapi.yaml
# Generate client SDK for Python
$ openapi-generator-cli generate -i openapi.yaml -g python -o ./python-client
$ openapi-generator-cli generate -i openapi.yaml -g python -o ./python-client
Tip: Always use
swagger-cli or openapi-generator-cli to validate and generate SDKs automatically. It reduces runtime errors.
Testing & Debugging Tools
Pro Tools
- Postman: Import OpenAPI spec for automated testing.
- Swagger Inspector: Test endpoints without writing any code.
- Stoplight Studio: Advanced visual OpenAPI editor.
- Redoc: Beautiful documentation generator.
Note: Combining Swagger UI with Postman or Redoc can create a full developer portal experience.