This topic provides a minimal yet complete example of an OpenAPI specification that follows best practices. It demonstrates how to structure endpoints, define schemas, and include essential metadata for clarity and consistency.
openapi: 3.0.3
info:
  title: Sample Customer API
  version: 1.2.0
  description: >
    Customer management endpoints. Pagination uses limit+cursor. Errors conform to ErrorResponse.
paths:
  /customers/{customerId}:
    get:
      summary: Get customer
      description: Returns a single customer by id. Requires customer.read scope.
      operationId: getCustomer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
          description: UUID of the customer
      responses:
        '200':
          description: Customer found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Not found
  /customers:
    post:
      summary: Create customer
      description: Creates a customer. Idempotent by externalId.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
components:
  schemas:
    Customer:
      title: Customer
      type: object
      required: [id, name]
      properties:
        id:
            type: string
            format: uuid
        name:
            type: string
        status:
            type: string
            enum: [ACTIVE, INACTIVE]
            description: Current lifecycle status
    CreateCustomerRequest:
      title: CreateCustomerRequest
      type: object
      required: [externalId, name]
      properties:
        externalId:
          type: string
        name:
          type: string
        status:
          type: string
          enum: [ACTIVE, INACTIVE]
    ErrorResponse:
      title: ErrorResponse
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true