Bunjs Apidog

APIDOG_PROJECT_ID=your-project-id     # From Apidog project settings
APIDOG_API_TOKEN=your-api-token       # From Apidog account settings

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

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

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

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:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{userId}:
    get:
      summary: Get user
      description: Retrieve a single user by ID
      operationId: getUser
      tags:
        - Users
      security:
        - bearerAuth: []
      x-apidog-folder: User Management/Users
      x-apidog-status: released
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

paths:
  /users:
    post:
      x-apidog-folder: User Management/Users

  /users/{userId}/profile:
    get:
      x-apidog-folder: User Management/Users/Profile

  /orders:
    post:
      x-apidog-folder: Order Management/Orders

paths:
  /users:
    post:
      x-apidog-status: released     # Fully implemented
  /beta/feature:
    post:
      x-apidog-status: testing      # In testing phase
  /legacy/api:
    get:
      x-apidog-status: deprecated   # Being phased out

paths:
  /users:
    post:
      x-apidog-maintainer: backend-team

  /admin/settings:
    put:
      x-apidog-maintainer: john-doe

# Save spec to file
cat > /tmp/api-spec.json << 'EOF'
{
  "openapi": "3.0.0",
  "info": { ... },
  "paths": { ... }
}
EOF

#!/bin/bash

# Environment variables (from .env)
APIDOG_PROJECT_ID="your-project-id"
APIDOG_API_TOKEN="your-api-token"

# Read OpenAPI spec
OPENAPI_SPEC=$(cat /tmp/api-spec.json | jq -c .)

# Import to Apidog
curl -X POST "https://api.apidog.com/v1/projects/${APIDOG_PROJECT_ID}/import-openapi" \
  -H "Authorization: Bearer ${APIDOG_API_TOKEN}" \
  -H "X-Apidog-Api-Version: 2024-03-28" \
  -H "Content-Type: application/json" \
  -d "{
    \"input\": \"${OPENAPI_SPEC}\",
    \"options\": {
      \"endpointOverwriteBehavior\": \"AUTO_MERGE\",
      \"schemaOverwriteBehavior\": \"AUTO_MERGE\",
      \"updateFolderOfChangedEndpoint\": false,
      \"prependBasePath\": false
    }
  }"

{
  "data": {
    "counters": {
      "endpointCreated": 3,
      "endpointUpdated": 2,
      "endpointFailed": 0,
      "endpointIgnored": 0,
      "schemaCreated": 5,
      "schemaUpdated": 1,
      "schemaFailed": 0,
      "schemaIgnored": 0,
      "endpointFolderCreated": 1,
      "endpointFolderUpdated": 0,
      "schemaFolderCreated": 0,
      "schemaFolderUpdated": 0
    },
    "errors": []
  }
}