API Documentation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

openapi: 3.1.0
info:
  title: Order Management API
  version: 2.3.1
  description: |
    The Order Management API enables e-commerce platforms to create,
    manage, and fulfill customer orders. This API follows RESTful
    conventions and uses JSON for request/response bodies.
  contact:
    name: API Support Team
    email: api-support@example.com
    url: https://developer.example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
 
servers:
  - url: https://api.example.com/v2
    description: Production environment
  - url: https://staging-api.example.com/v2
    description: Staging environment
  - url: http://localhost:3000/v2
    description: Local development
 
tags:
  - name: Orders
    description: Order lifecycle management
  - name: Products
    description: Product catalog operations
 
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      description: |
        Retrieves a paginated list of orders for the authenticated user.
        Orders are returned in reverse chronological order (newest first).
      tags: [Orders]
      parameters:
        - name: status
          in: query
          description: Filter orders by status
          schema:
            type: string
            enum: [pending, processing, shipped, delivered, cancelled]
        - name: limit
          in: query
          description: Maximum number of orders to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Pagination cursor from previous response
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
 
    post:
      operationId: createOrder
      summary: Create a new order
      description: |
        Creates a new order with the specified items and shipping details.
        The order will be in 'pending' status until payment is confirmed.
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              standard:
                summary: Standard order
                value:
                  items:
                    - productId: "prod_abc123"
                      quantity: 2
                  shippingAddress:
                    line1: "123 Main St"
                    city: "San Francisco"
                    state: "CA"
                    postalCode: "94102"
                    country: "US"
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
 
components:
  schemas:
    Order:
      type: object
      required: [id, status, items, totalAmount, createdAt]
      properties:
        id:
          type: string
          format: uuid
          description: Unique order identifier
          example: "ord_550e8400-e29b-41d4-a716-446655440000"
        status:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          description: Current order status
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
          minItems: 1
        totalAmount:
          $ref: '#/components/schemas/MonetaryAmount'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
 
    MonetaryAmount:
      type: object
      required: [cents, currency]
      properties:
        cents:
          type: integer
          description: Amount in smallest currency unit (cents for USD)
          example: 9999
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          description: ISO 4217 currency code
          example: "USD"
 
  responses:
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
 
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT-based authentication. Include your access token in the
        Authorization header: `Authorization: Bearer <token>`
 
security:
  - BearerAuth: []

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

paths:
  /orders/{orderId}:
    get:
      # Identifier used in code generation
      operationId: getOrderById
      
      # Short summary (shown in navigation)
      summary: Get order details
      
      # Long description (supports Markdown)
      description: |
        Retrieves complete details for a specific order, including:
        - Order status and timeline
        - Item details with current prices
        - Shipping information and tracking
        - Payment summary
        
        **Note:** Only the order owner or administrators can access order details.
      
      # Grouping for navigation
      tags: [Orders]
      
      # Request parameters
      parameters:
        - name: orderId
          in: path
          required: true
          description: |
            Unique order identifier. Can be either:
            - Order ID (e.g., `ord_abc123`)
            - Order number (e.g., `ORD-2024-00042`)
          schema:
            type: string
            pattern: "^(ord_[a-z0-9]+|ORD-\d{4}-\d{5})$"
          examples:
            orderId:
              summary: Order ID format
              value: "ord_abc123def456"
            orderNumber:
              summary: Order number format
              value: "ORD-2024-00042"
        
        - name: include
          in: query
          description: Additional data to include in response
          schema:
            type: array
            items:
              type: string
              enum: [tracking, payment_details, item_history]
          style: form
          explode: false
          example: ["tracking", "payment_details"]
      
      # All possible responses
      responses:
        '200':
          description: Order retrieved successfully
          headers:
            X-Cache-Status:
              description: Cache hit status
              schema:
                type: string
                enum: [HIT, MISS, BYPASS]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
              examples:
                pendingOrder:
                  summary: Order awaiting payment
                  value:
                    id: "ord_abc123"
                    status: "pending"
                    # ... additional fields
                shippedOrder:
                  summary: Order in transit
                  value:
                    id: "ord_def456"
                    status: "shipped"
                    trackingNumber: "1Z999AA10123456784"
        
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "ORDER_NOT_FOUND"
                message: "No order found with ID 'ord_invalid'"
        
        '403':
          description: Access denied to this order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      
      # Security override for this operation
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      
      # Deprecation notice
      deprecated: false
      
      # Link to external documentation
      externalDocs:
        description: Order lifecycle documentation
        url: https://docs.example.com/guides/order-lifecycle

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

asyncapi: 2.6.0
info:
  title: Order Events API
  version: 1.0.0
  description: |
    Real-time order status updates via WebSocket. Subscribe to receive
    notifications when orders change status, enabling real-time dashboards
    and automated workflows.
 
servers:
  production:
    url: wss://events.example.com/orders
    protocol: wss
    description: Production WebSocket server
  
  development:
    url: ws://localhost:8080/orders
    protocol: ws
    description: Local development server
 
channels:
  order/created:
    description: |
      Published when a new order is created. Contains complete order
      details for initial processing.
    subscribe:
      operationId: onOrderCreated
      summary: Receive new order notifications
      message:
        $ref: '#/components/messages/OrderCreatedEvent'
  
  order/status-changed:
    description: Published when order status transitions
    subscribe:
      operationId: onOrderStatusChanged
      summary: Receive order status changes
      message:
        $ref: '#/components/messages/OrderStatusChangedEvent'
  
  order/{orderId}/updates:
    description: Subscribe to updates for a specific order
    parameters:
      orderId:
        description: The order ID to subscribe to
        schema:
          type: string
    subscribe:
      operationId: onOrderUpdated
      message:
        $ref: '#/components/messages/OrderUpdatedEvent'
 
components:
  messages:
    OrderCreatedEvent:
      name: OrderCreated
      title: Order Created Event
      contentType: application/json
      payload:
        type: object
        required: [eventId, eventType, timestamp, order]
        properties:
          eventId:
            type: string
            format: uuid
            description: Unique event identifier for idempotency
          eventType:
            type: string
            const: "order.created"
          timestamp:
            type: string
            format: date-time
            description: When the event occurred
          order:
            $ref: '#/components/schemas/Order'
      examples:
        - name: standardOrder
          summary: New order created
          payload:
            eventId: "evt_abc123"
            eventType: "order.created"
            timestamp: "2024-01-15T14:30:00Z"
            order:
              id: "ord_xyz789"
              status: "pending"
              totalCents: 9999
    
    OrderStatusChangedEvent:
      name: OrderStatusChanged
      title: Order Status Changed Event
      contentType: application/json
      payload:
        type: object
        required: [eventId, eventType, timestamp, orderId, previousStatus, newStatus]
        properties:
          eventId:
            type: string
            format: uuid
          eventType:
            type: string
            const: "order.status_changed"
          timestamp:
            type: string
            format: date-time
          orderId:
            type: string
          previousStatus:
            $ref: '#/components/schemas/OrderStatus'
          newStatus:
            $ref: '#/components/schemas/OrderStatus'
          reason:
            type: string
            description: Optional reason for status change
 
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/OrderStatus'
        totalCents:
          type: integer
    
    OrderStatus:
      type: string
      enum: [pending, processing, shipped, delivered, cancelled]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

"""
The Order type represents a customer order in the system.
Orders progress through a lifecycle from creation to fulfillment.
"""
type Order {
  """
  Unique identifier for the order.
  Format: 'ord_' followed by 24 alphanumeric characters.
  """
  id: ID!
  
  """
  Human-readable order number for customer reference.
  Format: ORD-YYYY-NNNNN (e.g., ORD-2024-00042)
  """
  orderNumber: String!
  
  """
  Current status in the order lifecycle.
  See OrderStatus enum for possible values and their meanings.
  """
  status: OrderStatus!
  
  """
  Items included in this order.
  Minimum 1 item required, no maximum limit.
  """
  items: [OrderItem!]!
  
  """
  Total order value including taxes and shipping.
  Represented in the smallest currency unit (cents for USD).
  """
  totalAmount: Money!
  
  """
  Customer who placed the order.
  Null only for guest checkout (deprecated feature).
  """
  customer: Customer
  
  """
  Shipping destination.
  Required for physical goods, null for digital-only orders.
  """
  shippingAddress: Address
  
  """
  Tracking information once order is shipped.
  Null until carrier provides tracking number.
  """
  tracking: TrackingInfo
  
  """Gets detailed timeline of order events"""
  timeline(
    """Filter events by type (e.g., 'status_change', 'payment')"""
    eventTypes: [String!]
    """Maximum events to return"""
    limit: Int = 50
  ): [OrderEvent!]!
  
  """
  Legacy order reference ID.
  @deprecated Use 'orderNumber' for human-readable references.
  """
  legacyId: String @deprecated(reason: "Use orderNumber instead. Will be removed 2025-01-01")
  
  createdAt: DateTime!
  updatedAt: DateTime!
}
 
"""
Represents the possible states of an order in its lifecycle.
Orders transition through these states in a specific order,
though some transitions can be skipped (e.g., straight to cancelled).
"""
enum OrderStatus {
  """Order created but payment not yet received"""
  PENDING
  
  """Payment confirmed, awaiting fulfillment"""
  PROCESSING
  
  """Order packaged and handed to carrier"""
  SHIPPED
  
  """Successfully delivered to customer"""
  DELIVERED
  
  """Order cancelled by customer or system"""
  CANCELLED
  
  """Refund processed for returned order"""
  REFUNDED
}
 
"""
Mutations for order management.
All mutations require authentication and appropriate permissions.
"""
type Mutation {
  """
  Creates a new order from the current cart.
  Validates item availability and calculates final pricing.
  
  Returns the created order on success.
  Throws: OutOfStockError, PaymentRequiredError
  """
  createOrder(input: CreateOrderInput!): CreateOrderPayload!
  
  """
  Cancels an order that hasn't shipped yet.
  Full refund is processed automatically for paid orders.
  
  Throws: OrderNotFoundError, OrderAlreadyShippedError
  """
  cancelOrder(
    """ID of the order to cancel"""
    orderId: ID!
    """Reason for cancellation (shown to fulfillment team)"""
    reason: String
  ): CancelOrderPayload!
}
 
"""Input for creating a new order"""
input CreateOrderInput {
  """
  Cart ID to convert to order.
  Cart must belong to authenticated user and contain valid items.
  """
  cartId: ID!
  
  """
  Shipping address identifier.
  Must be a verified address from user's address book.
  """
  shippingAddressId: ID!
  
  """
  Selected shipping method.
  Must be a valid option for the order weight and destination.
  """
  shippingMethod: ShippingMethod!
  
  """Optional promotional code for discounts"""
  promoCode: String
  
  """Special instructions for delivery"""
  deliveryInstructions: String
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

<!DOCTYPE html>
<html>
<head>
  <title>Order API Documentation</title>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  
  <!-- Redoc styles -->
  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
  
  <style>
    body {
      margin: 0;
      padding: 0;
    }
  </style>
</head>
<body>
  <!-- Redoc element - documentation renders here -->
  <redoc spec-url='/api/openapi.yaml' 
         expand-responses="200,201"
         hide-download-button
         theme='{
           "colors": {
             "primary": { "main": "#5a67d8" }
           },
           "typography": {
             "fontSize": "15px",
             "fontFamily": "Roboto, sans-serif",
             "headings": {
               "fontFamily": "Montserrat, sans-serif"
             }
           },
           "rightPanel": {
             "backgroundColor": "#1e293b"
           }
         }'>
  </redoc>
  
  <!-- Redoc script -->
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Install: npm install @stoplight/elements
import { API } from '@stoplight/elements';
import '@stoplight/elements/styles.min.css';
 
interface APIDocsProps {
  specUrl: string;
  environment?: 'production' | 'staging' | 'development';
}
 
export function APIDocumentation({ specUrl, environment = 'production' }: APIDocsProps) {
  // Determine base URL based on environment
  const baseUrl = {
    production: 'https://api.example.com',
    staging: 'https://staging-api.example.com',
    development: 'http://localhost:3000',
  }[environment];
 
  return (
    <div className="api-docs-container">
      <API
        apiDescriptionUrl={specUrl}
        basePath="/"
        router="hash"
        layout="sidebar"
        
        // Customize try-it-out behavior
        tryItCredentialsPolicy="include"
        tryItCorsProxy="https://cors-proxy.example.com"
        
        // Override base URL for try-it-out
        tryItCredentialsPolicy="same-origin"
        
        // Logo and branding
        logo={<img src="/logo.svg" alt="Company Logo" />}
      />
    </div>
  );
}
 
// Usage in pages/docs.tsx or similar
export default function DocsPage() {
  return (
    <Layout>
      <APIDocumentation 
        specUrl="/api/openapi.yaml"
        environment={process.env.NEXT_PUBLIC_ENVIRONMENT as any}
      />
    </Layout>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

/**
 * Service for managing customer orders throughout their lifecycle.
 * 
 * This service handles order creation, status transitions, and retrieval.
 * All operations are transactional and emit domain events for downstream
 * processing.
 * 
 * @example Basic order creation
 * ```typescript
 * const orderService = new OrderService(repository, eventBus);
 * const order = await orderService.createOrder({
 *   customerId: 'cust_abc123',
 *   items: [{ productId: 'prod_xyz', quantity: 2 }],
 *   shippingAddress: customerAddress,
 * });
 * console.log(`Order created: ${order.orderNumber}`);
 * ```
 * 
 * @see {@link Order} for the order entity structure
 * @see {@link OrderRepository} for data access patterns
 */
export class OrderService {
  private readonly repository: OrderRepository;
  private readonly eventBus: EventBus;
  private readonly pricingService: PricingService;
 
  /**
   * Creates a new OrderService instance.
   * 
   * @param repository - Repository for order persistence
   * @param eventBus - Event bus for publishing domain events
   * @param pricingService - Service for calculating order totals
   */
  constructor(
    repository: OrderRepository,
    eventBus: EventBus,
    pricingService: PricingService
  ) {
    this.repository = repository;
    this.eventBus = eventBus;
    this.pricingService = pricingService;
  }
 
  /**
   * Creates a new order with the specified items and shipping details.
   * 
   * The order is created in PENDING status and awaits payment confirmation.
   * An OrderCreated domain event is published upon successful creation.
   * 
   * @param options - Order creation parameters
   * @param options.customerId - ID of the customer placing the order
   * @param options.items - Array of items to include (minimum 1)
   * @param options.shippingAddress - Delivery address for physical goods
   * @param options.promoCode - Optional promotional code for discounts
   * 
   * @returns The created order with calculated totals
   * 
   * @throws {ValidationError} If items array is empty or contains invalid products
   * @throws {OutOfStockError} If any item exceeds available inventory
   * @throws {InvalidAddressError} If shipping address fails validation
   * @throws {ExpiredPromoError} If promotional code is expired or invalid
   * 
   * @example Creating an order with a promo code
   * ```typescript
   * try {
   *   const order = await orderService.createOrder({
   *     customerId: customer.id,
   *     items: cartItems.map(i => ({ productId: i.product.id, quantity: i.qty })),
   *     shippingAddress: customer.defaultAddress,
   *     promoCode: 'SUMMER20',
   *   });
   * } catch (error) {
   *   if (error instanceof ExpiredPromoError) {
   *     showMessage('Promo code has expired');
   *   }
   * }
   * ```
   * 
   * @since 2.0.0
   * @category Order Management
   */
  async createOrder(options: CreateOrderOptions): Promise<Order> {
    // Validate inputs
    this.validateOrderOptions(options);
    
    // Calculate pricing
    const pricing = await this.pricingService.calculate({
      items: options.items,
      promoCode: options.promoCode,
    });
    
    // Create and persist order
    const order = Order.create({
      ...options,
      totalAmount: pricing.total,
      discounts: pricing.appliedDiscounts,
    });
    
    await this.repository.save(order);
    
    // Publish domain event
    await this.eventBus.publish(new OrderCreatedEvent(order));
    
    return order;
  }
 
  /**
   * Retrieves an order by its unique identifier.
   * 
   * @param orderId - The order's unique ID (format: ord_*)
   * @returns The order if found, null otherwise
   * 
   * @example
   * ```typescript
   * const order = await orderService.getById('ord_abc123');
   * if (order) {
   *   console.log(`Status: ${order.status}`);
   * }
   * ```
   */
  async getById(orderId: OrderId): Promise<Order | null> {
    return this.repository.findById(orderId);
  }
 
  /**
   * Transitions an order to SHIPPED status.
   * 
   * @param orderId - Order to mark as shipped
   * @param trackingInfo - Carrier and tracking number details
   * 
   * @throws {OrderNotFoundError} If order doesn't exist
   * @throws {InvalidStateTransitionError} If order isn't in PROCESSING status
   * 
   * @fires OrderShippedEvent
   * 
   * @deprecated Use {@link fulfillOrder} instead, which handles partial shipments.
   * This method will be removed in version 3.0.0.
   */
  async markAsShipped(
    orderId: OrderId,
    trackingInfo: TrackingInfo
  ): Promise<void> {
    // Implementation...
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# .github/workflows/docs.yml
name: API Documentation
 
on:
  push:
    branches: [main]
    paths:
      - 'src/api/**'
      - 'docs/**'
      - 'openapi.yaml'
  pull_request:
    branches: [main]
    paths:
      - 'src/api/**'
      - 'docs/**'
      - 'openapi.yaml'
 
jobs:
  validate:
    name: Validate OpenAPI Spec
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate OpenAPI specification
        uses: char0n/swagger-editor-validate@v1
        with:
          definition-file: openapi.yaml
      
      - name: Lint OpenAPI with Spectral
        run: |
          npx @stoplight/spectral-cli lint openapi.yaml \
            --ruleset .spectral.yaml
      
      - name: Check for breaking changes
        if: github.event_name == 'pull_request'
        run: |
          npx oasdiff breaking \
            https://api.example.com/openapi.yaml \
            openapi.yaml
 
  generate:
    name: Generate Documentation
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      # Generate TypeScript API reference from source
      - name: Generate TypeDoc reference
        run: npx typedoc \
          --out docs/api-reference \
          --entryPoints src/api/index.ts \
          --plugin typedoc-plugin-markdown
      
      # Generate OpenAPI documentation
      - name: Generate OpenAPI docs (Redoc)
        run: |
          npx @redocly/cli build-docs openapi.yaml \
            --output docs/rest-api/index.html \
            --config redocly.yaml
      
      # Bundle OpenAPI spec
      - name: Bundle OpenAPI specification
        run: |
          npx @redocly/cli bundle openapi.yaml \
            --output docs/openapi.bundled.yaml
      
      # Generate SDK documentation
      - name: Generate SDK reference
        run: npm run docs:sdk
      
      - name: Upload documentation artifacts
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: docs/
 
  deploy:
    name: Deploy Documentation
    needs: generate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Download documentation artifacts
        uses: actions/download-artifact@v4
        with:
          name: documentation
          path: docs/
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          cname: docs.example.com
      
      # Notify documentation platform
      - name: Trigger ReadMe sync
        run: |
          curl -X POST "https://dash.readme.com/api/v1/docs" \
            -H "Authorization: Basic ${{ secrets.README_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"sync": true}'