OpenAPI: Health Check Endpoint Definition

Documenting Health Check Endpoints in OpenAPI

Health check endpoints are critical for container orchestration (Kubernetes), load balancers, and monitoring systems. Following a consistent format ensures compatibility with infrastructure tooling.

Basic Health Check

paths:
  /health:
    get:
      summary: Application health check
      tags:
        - Operations
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: Application is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Application is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

Health Response Schema

components:
  schemas:
    HealthResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - pass
            - warn
            - fail
          description: Overall health status
        version:
          type: string
          description: Application version
        uptime:
          type: integer
          description: Uptime in seconds
        checks:
          type: object
          properties:
            database:
              $ref: '#/components/schemas/DependencyCheck'
            cache:
              $ref: '#/components/schemas/DependencyCheck'
            externalApi:
              $ref: '#/components/schemas/DependencyCheck'
    DependencyCheck:
      type: object
      properties:
        status:
          type: string
          enum:
            - pass
            - fail
        responseTime:
          type: integer
          description: Response time in milliseconds
        message:
          type: string

Kubernetes Probes

Define separate endpoints for Kubernetes liveness and readiness:

/health/live:
  get:
    summary: Liveness probe
    description: Returns 200 if the process is running
/health/ready:
  get:
    summary: Readiness probe
    description: Returns 200 if the app can serve traffic

Security Considerations

Health check endpoints should be excluded from authentication (security: []) to allow load balancers and orchestrators to probe them without credentials. However, detailed dependency information should only be exposed to authenticated internal clients.