Agent Skills: API Documentation Generator

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:

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:

{
  "flightId": 123,
  "passengers": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@email.com",
      "dateOfBirth": "1990-01-15",
      "passportNumber": "AB1234567"
    }
  ],
  "contactEmail": "john.doe@email.com",
  "paymentMethod": "card"
}

Response 201:

{
  "bookingId": "BK-2024-789456",
  "status": "confirmed",
  "totalPrice": 299.99,
  "currency": "USD",
  "confirmationSentTo": "john.doe@email.com"
}

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

2. Extract Request/Response Models:

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

3. Identify Authentication:

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

4. Generate Examples:

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

5. Create OpenAPI Spec:

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

6. Generate Human-Readable Docs:

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

7. 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

| Format | File | Use Case | |--------|------|----------| | OpenAPI 3.0 | openapi.yaml | Standard spec, tools | | Swagger UI | /swagger | Interactive testing | | Markdown | README.md | GitHub, wikis | | Postman | collection.json | Team testing | | cURL | examples.md | Quick testing |

Benefits

| Metric | Before | After | Improvement | |--------|--------|-------|-------------| | Documentation time | 2 days | 5 min | 500x faster | | Accuracy | Often wrong | Always correct | From code source | | Maintenance | Manual updates | Auto-generated | Zero effort | | Partner onboarding | 1 week | 1 day | 5x faster |