Home / OpenAPI examples reference

OpenAPI examples reference

This reference provides templates, examples, and reusable patterns for creating OpenAPI documentation. Use these examples as starting points for your own documentation projects.

---

Quick start templates

Basic OpenAPI document structure

openapi: 3.0.1
info:
  title: Your API Name
  version: 1.0.0
  description: |
    Brief description of what your API does.

    **Key Features:**
    - Feature 1
    - Feature 2
    - Feature 3
  contact:
    name: API Support Team
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

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

paths:
  # Your endpoints go here

components:
  schemas:
    # Your data models go here

Complete endpoint template

/your-endpoint:
  post:
    summary: Brief description of what this endpoint does
    description: |
      Detailed explanation of the endpoint behavior.

      **Business Rules:**
      - Rule 1
      - Rule 2

      **Workflow:**
      1. Step 1
      2. Step 2
      3. Step 3
    tags:
      - Your Tag Name
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/YourModel'
          examples:
            basic_example:
              summary: Basic example
              value:
                field1: "value1"
                field2: "value2"
            advanced_example:
              summary: Advanced example with all fields
              value:
                field1: "value1"
                field2: "value2"
                optionalField: "optional value"
    responses:
      '200':
        description: Success response
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YourResponseModel'
            example:
              status: "success"
              data: {}
      '400':
        description: Invalid request data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorResponse'
            example:
              message: "Invalid input data"
              timestamp: "2026-01-25T10:30:00.000Z"
              status: 400
              error: "Bad Request"

---

Customer API examples

These examples demonstrate real-world OpenAPI patterns using the Customer Management API as a concrete use case.

Complete customer schema

components:
  schemas:
    Customer:
      type: object
      required:
        - id
        - name
        - type
      properties:
        id:
          type: string
          pattern: '^CUST[0-9]{3}$'
          description: Unique customer identifier (format CUSTXXX)
          example: "CUST001"
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Customer full name
          example: "Alice Johnson"
        phone:
          type: string
          pattern: '^[0-9\-\+\(\)\s]+$'
          description: Customer phone number
          example: "555-0123"
        type:
          $ref: '#/components/schemas/CustomerType'
        address:
          $ref: '#/components/schemas/Address'
      description: Complete customer information including contact details and address

    Address:
      type: object
      required:
        - street
        - city
        - state
        - zipCode
        - country
      properties:
        street:
          type: string
          description: Street address
          example: "123 Main St"
        city:
          type: string
          description: City name
          example: "New York"
        state:
          type: string
          pattern: '^[A-Z]{2}$'
          description: State code (2 letters)
          example: "NY"
        zipCode:
          type: string
          pattern: '^[0-9]{5}(-[0-9]{4})?$'
          description: ZIP code (5 digits or ZIP+4 format)
          example: "10001"
        country:
          type: string
          description: Country name
          example: "USA"
      description: Complete address information

    CustomerType:
      type: string
      enum:
        - INDIVIDUAL
        - BUSINESS
        - VIP
        - PREMIUM
      description: |
        Customer classification levels:
        - **INDIVIDUAL**: Regular individual customers
        - **BUSINESS**: Business/corporate accounts
        - **VIP**: High-value customers with premium support
        - **PREMIUM**: Enterprise customers with dedicated services

    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message
          example: "Customer with ID CUST001 not found"
        timestamp:
          type: string
          format: date-time
          description: When the error occurred
          example: "2026-01-25T10:30:00.000Z"
        status:
          type: integer
          description: HTTP status code
          example: 404
        error:
          type: string
          description: HTTP status text
          example: "Not Found"
        path:
          type: string
          description: Request path that caused the error
          example: "/customer/CUST001"
      description: Standard error response format

Customer request examples

Create customer examples

# Individual Customer
{
  "id": "CUST001",
  "name": "Alice Johnson",
  "phone": "555-0123",
  "type": "INDIVIDUAL",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  }
}

# Business Customer
{
  "id": "CUST002",
  "name": "Acme Corporation",
  "phone": "555-0199",
  "type": "BUSINESS",
  "address": {
    "street": "456 Business Ave",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60601",
    "country": "USA"
  }
}

# VIP Customer
{
  "id": "CUST003",
  "name": "Premium Client LLC",
  "phone": "555-0200",
  "type": "VIP",
  "address": {
    "street": "789 Luxury Blvd",
    "city": "Beverly Hills",
    "state": "CA",
    "zipCode": "90210",
    "country": "USA"
  }
}

# Minimal Required Fields Only
{
  "id": "CUST004",
  "name": "Minimal Customer",
  "type": "INDIVIDUAL"
}

Update customer examples

# Complete Update (PUT)
{
  "id": "CUST001",
  "name": "Alice Johnson Updated",
  "phone": "555-9999",
  "type": "PREMIUM",
  "address": {
    "street": "456 Updated Ave",
    "city": "New York",
    "state": "NY",
    "zipCode": "10002",
    "country": "USA"
  }
}

# Partial Update (PATCH)
{
  "phone": "555-PATCH",
  "type": "BUSINESS"
}

Batch create example

[
  {
    "id": "BATCH001",
    "name": "Batch Customer 1",
    "type": "INDIVIDUAL",
    "phone": "555-1001",
    "address": {
      "street": "1 Batch Street",
      "city": "Boston",
      "state": "MA",
      "zipCode": "02101",
      "country": "USA"
    }
  },
  {
    "id": "BATCH002",
    "name": "Batch Customer 2",
    "type": "BUSINESS",
    "phone": "555-1002",
    "address": {
      "street": "2 Batch Avenue",
      "city": "Boston",
      "state": "MA",
      "zipCode": "02102",
      "country": "USA"
    }
  },
  {
    "id": "BATCH003",
    "name": "Batch Customer 3",
    "type": "VIP",
    "phone": "555-1003",
    "address": {
      "street": "3 Batch Boulevard",
      "city": "Boston",
      "state": "MA",
      "zipCode": "02103",
      "country": "USA"
    }
  }
]

---

Response examples

These examples show the actual JSON responses returned by the Customer Management API for both successful operations and error conditions.

Success responses

Single customer response

{
  "name": "Alice Johnson",
  "id": "CUST001",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA",
    "formattedAddress": "123 Main St, New York, NY 10001, USA"
  },
  "phone": "555-0123",
  "type": "VIP",
  "city": "New York",
  "businessCustomer": false,
  "highValueCustomer": true
}

Paginated customer list response

{
  "content": [
    {
      "name": "Alice Johnson",
      "id": "CUST001",
      "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "zipCode": "10001",
        "country": "USA",
        "formattedAddress": "123 Main St, New York, NY 10001, USA"
      },
      "phone": "555-0123",
      "type": "VIP",
      "city": "New York",
      "businessCustomer": false,
      "highValueCustomer": true
    },
    {
      "name": "Bob Smith",
      "id": "CUST002",
      "address": {
        "street": "456 Oak Ave",
        "city": "Boston",
        "state": "MA",
        "zipCode": "02101",
        "country": "USA",
        "formattedAddress": "456 Oak Ave, Boston, MA 02101, USA"
      },
      "phone": "555-0124",
      "type": "BUSINESS",
      "city": "Boston",
      "businessCustomer": true,
      "highValueCustomer": false
    }
  ],
  "page": 0,
  "size": 10,
  "totalPages": 1,
  "totalElements": 2,
  "first": true,
  "last": true,
  "empty": false,
  "numberOfElements": 2
}

Simple success message

"Customer added successfully"

Error responses

Validation Error (400)

{
  "message": "Invalid customer data: Customer ID format must be CUSTXXX",
  "timestamp": "2026-01-25T10:30:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "path": "/customer"
}

Not found error (404)

{
  "message": "Customer with ID CUST999 is not found",
  "timestamp": "2026-01-25T10:30:00.000Z",
  "status": 404,
  "error": "Not Found",
  "path": "/customer/CUST999"
}

Conflict error (409)

{
  "message": "Customer with ID CUST001 already exists",
  "timestamp": "2026-01-25T10:30:00.000Z",
  "status": 409,
  "error": "Conflict",
  "path": "/customer"
}

Authentication required (401)

{
  "timestamp": "2026-01-25T10:30:00.000Z",
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource",
  "path": "/customer/CUST001"
}

Insufficient permissions (403)

{
  "timestamp": "2026-01-25T10:30:00.000Z",
  "status": 403,
  "error": "Forbidden",
  "message": "Access forbidden: requires ADMIN role",
  "path": "/customer/CUST001"
}

---

Common OpenAPI patterns

These reusable patterns help you document API features consistently across different endpoints and specifications.

Parameter documentation patterns

Path parameters

parameters:
  - name: id
    in: path
    required: true
    description: Unique customer identifier
    schema:
      type: string
      pattern: '^CUST[0-9]{3}$'
    example: "CUST001"

Query parameters

parameters:
  - name: page
    in: query
    required: false
    description: Page number for pagination (starts at 0)
    schema:
      type: integer
      minimum: 0
      default: 0
    example: 0
  - name: size
    in: query
    required: false
    description: Number of items per page
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 10
    example: 10
  - name: type
    in: query
    required: false
    description: Filter by customer type
    schema:
      $ref: '#/components/schemas/CustomerType'
    example: "VIP"

Multiple examples pattern

content:
  application/json:
    schema:
      $ref: '#/components/schemas/Customer'
    examples:
      minimal_customer:
        summary: Minimal required fields
        description: Example with only required customer information
        value:
          id: "CUST001"
          name: "John Doe"
          type: "INDIVIDUAL"
      complete_customer:
        summary: Complete customer information
        description: Example including all optional fields
        value:
          id: "CUST002"
          name: "Jane Smith"
          phone: "555-0123"
          type: "VIP"
          address:
            street: "123 Complete St"
            city: "Full City"
            state: "CA"
            zipCode: "90210"
            country: "USA"
      business_customer:
        summary: Business customer example
        description: Example of a business/corporate customer
        value:
          id: "CUST003"
          name: "Acme Corporation"
          phone: "555-0199"
          type: "BUSINESS"
          address:
            street: "456 Business Ave"
            city: "Commerce City"
            state: "TX"
            zipCode: "75001"
            country: "USA"

Validation rules patterns

Customer:
  type: object
  properties:
    id:
      type: string
      pattern: '^CUST[0-9]{3}$'              # Regex validation
      description: Must follow format CUSTXXX where XXX is 3 digits
      example: "CUST001"
    name:
      type: string
      minLength: 1                           # Minimum length
      maxLength: 100                         # Maximum length
      description: Customer full name (1-100 characters)
      example: "Alice Johnson"
    phone:
      type: string
      pattern: '^[0-9\-\+\(\)\s]+$'         # Phone format validation
      description: Phone number (numbers, hyphens, parentheses, spaces, plus signs allowed)
      example: "555-0123"
    email:
      type: string
      format: email                          # Built-in email validation
      description: Valid email address
      example: "alice@example.com"
    age:
      type: integer
      minimum: 0                             # Minimum value
      maximum: 150                           # Maximum value
      description: Customer age (0-150 years)
      example: 30
    registrationDate:
      type: string
      format: date-time                      # ISO 8601 date-time format
      description: When the customer registered (ISO 8601 format)
      example: "2026-01-25T10:30:00.000Z"

---

Testing data sets

Use these predefined test data sets to validate your API documentation and test various scenarios systematically.

Complete test customer set

Use these for comprehensive testing scenarios:

# Test Customer 1 - Individual
{
  "id": "TEST001",
  "name": "Individual Test Customer",
  "phone": "555-0001",
  "type": "INDIVIDUAL",
  "address": {
    "street": "1 Test Street",
    "city": "Test City",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  }
}

# Test Customer 2 - Business
{
  "id": "TEST002",
  "name": "Business Test Corp",
  "phone": "555-0002",
  "type": "BUSINESS",
  "address": {
    "street": "2 Business Ave",
    "city": "Commerce City",
    "state": "CA",
    "zipCode": "90210",
    "country": "USA"
  }
}

# Test Customer 3 - VIP
{
  "id": "TEST003",
  "name": "VIP Test Customer",
  "phone": "555-0003",
  "type": "VIP",
  "address": {
    "street": "3 VIP Boulevard",
    "city": "Luxury Town",
    "state": "FL",
    "zipCode": "33101",
    "country": "USA"
  }
}

# Test Customer 4 - Premium
{
  "id": "TEST004",
  "name": "Premium Test Customer",
  "phone": "555-0004",
  "type": "PREMIUM",
  "address": {
    "street": "4 Premium Place",
    "city": "Elite City",
    "state": "TX",
    "zipCode": "75001",
    "country": "USA"
  }
}

# Test Customer 5 - Minimal (only required fields)
{
  "id": "TEST005",
  "name": "Minimal Test Customer",
  "type": "INDIVIDUAL"
}

Edge case test data

# Maximum length name
{
  "id": "EDGE001",
  "name": "This is a very long customer name designed to test the maximum length validation rules",
  "type": "INDIVIDUAL"
}

# Special characters in address
{
  "id": "EDGE002",
  "name": "Special Character Customer",
  "type": "BUSINESS",
  "address": {
    "street": "123 O'Reilly St, Apt #4B",
    "city": "Saint-Jean-sur-Richelieu",
    "state": "QC",
    "zipCode": "J3B-1A1",
    "country": "Canada"
  }
}

# International phone number
{
  "id": "EDGE003",
  "name": "International Customer",
  "phone": "+1-800-555-0123",
  "type": "VIP",
  "address": {
    "street": "456 International Blvd",
    "city": "Global City",
    "state": "WA",
    "zipCode": "98101",
    "country": "USA"
  }
}

---

Copy-paste cURL commands

Ready-to-use command line examples for testing and demonstrating your API functionality.

Basic CRUD operations

# Create Customer
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CURL001",
    "name": "cURL Test Customer",
    "phone": "555-0123",
    "type": "INDIVIDUAL",
    "address": {
      "street": "123 cURL Street",
      "city": "Command City",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA"
    }
  }'

# Get Customer
curl http://localhost:8080/customer/CURL001

# Update Customer (PUT)
curl -X PUT http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CURL001",
    "name": "Updated cURL Customer",
    "phone": "555-9999",
    "type": "VIP",
    "address": {
      "street": "456 Updated Street",
      "city": "New Command City",
      "state": "NY",
      "zipCode": "10002",
      "country": "USA"
    }
  }'

# Partial Update (PATCH)
curl -X PATCH http://localhost:8080/customer/CURL001 \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "555-PATCH",
    "type": "PREMIUM"
  }'

# Delete Customer (requires admin authentication)
curl -u testadmin:admin123 -X DELETE http://localhost:8080/customer/CURL001

Search and pagination

# Get all customers (paginated)
curl "http://localhost:8080/customers"

# Get customers with custom pagination
curl "http://localhost:8080/customers?page=0&size=5"

# Search by name
curl "http://localhost:8080/customers/search?name=Test"

# Search by city
curl "http://localhost:8080/customers/search?city=New York"

# Search by customer type
curl "http://localhost:8080/customers/search?type=VIP"

# Search by state
curl "http://localhost:8080/customers/search?state=CA"

# Complex search with multiple parameters
curl "http://localhost:8080/customers/search?type=BUSINESS&state=CA&page=0&size=10"

Error testing

# Test duplicate ID (409 error)
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "CURL001", "name": "Duplicate Test", "type": "INDIVIDUAL"}'

# Test invalid customer type (400 error)
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "ERROR001", "name": "Error Test", "type": "INVALID_TYPE"}'

# Test missing required fields (400 error)
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"name": "Missing ID Customer"}'

# Test not found (404 error)
curl http://localhost:8080/customer/NONEXISTENT

# Test unauthorized access (401 error)
curl -X DELETE http://localhost:8080/customer/CURL001

# Test insufficient permissions (403 error)
curl -u testuser:user123 -X DELETE http://localhost:8080/customer/CURL001

---

Use these examples as templates for your own API documentation. All examples are tested against the Customer Management API and can be copied directly into your specifications or testing workflows.