bunjs-apidog

What this skill does

# Bun.js OpenAPI and Apidog Integration

## Overview

This skill covers OpenAPI specification creation and Apidog integration for Bun.js TypeScript backend applications. Learn how to document APIs with OpenAPI 3.0, use Apidog-specific extensions, import specifications via REST API, and maintain synchronized API documentation.

**When to use this skill:**
- Creating OpenAPI specifications for API documentation
- Synchronizing API specs with Apidog projects
- Importing endpoints and schemas to Apidog
- Managing API documentation lifecycle

**See also:**
- **dev:bunjs** - Core Bun patterns, HTTP servers, database access
- **dev:bunjs-architecture** - Layered architecture, camelCase conventions
- **dev:bunjs-production** - Production deployment patterns

## Why Apidog

Apidog is a comprehensive API development platform that combines:
- **API Design** - Visual OpenAPI editor
- **API Documentation** - Auto-generated, always up-to-date docs
- **API Testing** - Built-in testing tools
- **API Mocking** - Mock servers for frontend development
- **Team Collaboration** - Shared workspace for teams

## Environment Variables

**Required:**
```bash
APIDOG_PROJECT_ID=your-project-id     # From Apidog project settings
APIDOG_API_TOKEN=your-api-token       # From Apidog account settings
```

**How to get these:**
1. **APIDOG_PROJECT_ID**: Open your Apidog project → Settings → Project ID
2. **APIDOG_API_TOKEN**: Apidog Account → Settings → API Tokens → Generate Token

## OpenAPI Spec Creation

### Basic Structure

```yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API for managing resources

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: http://localhost:3000
    description: Development server

components:
  schemas:
    # Define reusable data models here
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  # Define API endpoints here
```

### Field Naming: camelCase (CRITICAL)

**ALWAYS use camelCase for all JSON API field names in OpenAPI specs.**

```yaml
components:
  schemas:
    User:
      type: object
      required:
        - userId
        - emailAddress
      properties:
        userId:              # ✅ camelCase
          type: string
          format: uuid
        emailAddress:        # ✅ camelCase
          type: string
          format: email
        firstName:           # ✅ camelCase
          type: string
        lastName:            # ✅ camelCase
          type: string
        phoneNumber:         # ✅ camelCase
          type: string
        isActive:            # ✅ camelCase boolean
          type: boolean
        createdAt:           # ✅ camelCase timestamp
          type: string
          format: date-time
        updatedAt:           # ✅ camelCase timestamp
          type: string
          format: date-time

    # ❌ WRONG: snake_case
    # user_id, email_address, first_name, created_at

    # ❌ WRONG: PascalCase
    # UserId, EmailAddress, FirstName, CreatedAt
```

**Why camelCase:**
- Native to JavaScript/JSON ecosystem
- Industry standard (Google, Microsoft, AWS)
- TypeScript friendly (1:1 mapping)
- OpenAPI/Swagger convention
- Auto-generated clients expect it

### Schema Design

**Define reusable schemas in `components.schemas`:**

```yaml
components:
  schemas:
    User:
      type: object
      required:
        - userId
        - emailAddress
        - firstName
        - lastName
      properties:
        userId:
          type: string
          format: uuid
          description: Unique user identifier
        emailAddress:
          type: string
          format: email
          description: User email address
        firstName:
          type: string
          minLength: 2
          maxLength: 100
        lastName:
          type: string
          minLength: 2
          maxLength: 100
        phoneNumber:
          type: string
          pattern: '^\+?[1-9]\d{1,14}$'
        role:
          type: string
          enum: [user, admin, moderator]
          default: user
        isActive:
          type: boolean
          default: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - emailAddress
        - password
        - firstName
        - lastName
      properties:
        emailAddress:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 8
        firstName:
          type: string
          minLength: 2
        lastName:
          type: string
          minLength: 2
        phoneNumber:
          type: string
        role:
          type: string
          enum: [user, admin, moderator]

    UserListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Pagination:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
        totalPages:
          type: integer

    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        type:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
```

### Endpoint Definitions

**Define endpoints in `paths`:**

```yaml
paths:
  /users:
    get:
      summary: List users
      description: Retrieve paginated list of users
      operationId: listUsers
      tags:
        - Users
      security:
        - bearerAuth: []
      x-apidog-folder: User Management/Users
      x-apidog-status: released
      x-apidog-maintainer: backend-team
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [createdAt, firstName, emailAddress]
        - name: orderBy
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      summary: Create user
      description: Create a new user account
      operationId: createUser
      tags:
        - Users
      x-apidog-folder: User Management/Users
      x-apidog-status: released
      x-apidog-maintainer: backend-team
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '400':
          description: Invalid request
          content:
            ap