API Documentation Generator

Automatically generates comprehensive OpenAPI/Swagger documentation from your API code, including endpoints, request/response schemas, and usage examples.

🎯 Use Case Demo

Scenario: API Documentation for External Consumers

Before (Manual Process):

Team needs to document API for partner integration:
1. Open each controller, list endpoints manually
2. Document request/response formats in Word doc
3. Write example requests in Postman
4. Export Postman collection
5. Code changes → documentation out of sync
6. Partners report incorrect documentation

Time: 1-2 days, always outdated

After (With This Skill):

Developer: "Generate API documentation for FlightBookingAPI"

Agent Response:
```
📚 API DOCUMENTATION GENERATED
═══════════════════════════════════════════════════════════════

🌐 API: Flight Booking API
📌 Version: 1.0.0
🔗 Base URL: https://api.flightbooking.com/v1

═══════════════════════════════════════════════════════════════
📋 ENDPOINTS DOCUMENTED
═══════════════════════════════════════════════════════════════

✈️ FLIGHTS
─────────────────────────────────────────────

GET /api/flights
📝 Search for available flights
🔐 Auth: None (public)

Query Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| origin | string | ✅ | IATA airport code (e.g., "JFK") |
| destination | string | ✅ | IATA airport code (e.g., "LAX") |
| departureDate | date | ✅ | Format: YYYY-MM-DD |
| passengers | integer | ❌ | Default: 1, Max: 9 |
| cabinClass | string | ❌ | economy, business, first |

Response 200:
```json
{
"flights": [
{
"id": 123,
"flightNumber": "AA1234",
"airline": "American Airlines",
"origin": "JFK",
"destination": "LAX",
"departureTime": "2024-12-25T08:00:00Z",
"arrivalTime": "2024-12-25T11:30:00Z",
"duration": "5h 30m",
"price": {
"amount": 299.99,
"currency": "USD"
},
"seatsAvailable": 45
}
],
"totalResults": 24,
"page": 1,
"pageSize": 10
}
```

Example cURL:
```bash
curl -X GET "https://api.flightbooking.com/v1/api/flights?\
origin=JFK&destination=LAX&departureDate=2024-12-25" \
-H "Accept: application/json"
```

GET /api/flights/{id}
📝 Get flight details by ID
🔐 Auth: None (public)

Path Parameters:
| Name | Type | Description |
|------|------|-------------|
| id | integer | Flight ID |

Response 200: Flight object
Response 404: Flight not found

─────────────────────────────────────────────
🎫 BOOKINGS
─────────────────────────────────────────────

POST /api/bookings
📝 Create a new booking
🔐 Auth: Bearer Token (required)

Request Body:
```json
{
"flightId": 123,
"passengers": [
{
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"dateOfBirth": "1990-01-15",
"passportNumber": "AB1234567"
}
],
"contactEmail": "[email protected]",
"paymentMethod": "card"
}
```

Response 201:
```json
{
"bookingId": "BK-2024-789456",
"status": "confirmed",
"totalPrice": 299.99,
"currency": "USD",
"confirmationSentTo": "[email protected]"
}
```

Error Responses:
| Status | Description |
|--------|-------------|
| 400 | Invalid request body |
| 401 | Authentication required |
| 404 | Flight not found |
| 409 | No seats available |
| 422 | Validation failed |

GET /api/bookings/{id}
📝 Get booking by ID
🔐 Auth: Bearer Token (owner or admin)

DELETE /api/bookings/{id}
📝 Cancel a booking
🔐 Auth: Bearer Token (owner or admin)

Response 200: Cancellation confirmed with refund details
Response 400: Booking not cancellable (past departure)

═══════════════════════════════════════════════════════════════
📄 FILES GENERATED
═══════════════════════════════════════════════════════════════

✅ docs/api/openapi.yaml - OpenAPI 3.0 specification
✅ docs/api/README.md - Human-readable documentation
✅ docs/api/postman-collection.json - Postman import file
✅ docs/api/examples/ - Request/response examples

═══════════════════════════════════════════════════════════════
🔗 SWAGGER UI
═══════════════════════════════════════════════════════════════

Your API documentation is available at:
http://localhost:5000/swagger

The OpenAPI spec has been updated with:
• 4 endpoints documented
• 3 schema definitions
• 12 example responses
• Authentication configuration

═══════════════════════════════════════════════════════════════
```

Time Saved: 2 days → 5 minutes (500x faster, always accurate)

Agent Instructions

When this skill is activated:

1. Analyze Controllers:

- Find all API controller classes - Extract endpoints (routes, HTTP methods) - Parse route templates and parameters

1. Extract Request/Response Models:

- Find parameter types and model classes - Document properties with types - Note required vs optional fields - Include validation rules

1. Identify Authentication:

- Check for [Authorize] attributes - Note authentication schemes - Document required scopes/roles

1. Generate Examples:

- Create realistic example requests - Generate sample responses - Include error response examples

1. Create OpenAPI Spec:

- Generate openapi.yaml file - Include all paths and schemas - Add descriptions and examples - Configure security schemes

1. Generate Human-Readable Docs:

- Create Markdown documentation - Organize by resource/feature - Include cURL examples - Add quick-start guide

1. Export Formats:

- OpenAPI 3.0 YAML - Postman collection - Markdown documentation

Example Prompts

• "Generate API documentation"
• "Create OpenAPI spec for our API"
• "Document the Flights endpoint"
• "Export Postman collection from API"
• "Update Swagger documentation"

Output Formats

Benefits