OpenAPI Contracts¶

What Are the OpenAPI Specs?¶

The architecture/specs/ directory contains an OpenAPI 3.0 YAML file for every NovaTrek microservice (22 services). Each file is a machine-readable contract that defines:

• Endpoints — every REST route, HTTP method, and operation ID
• Request/response schemas — exact field names, data types, nullable annotations, and enumerations
• Security requirements — authentication schemes (e.g., BearerAuth)
• Server URLs — base paths for each deployment environment
• Contact metadata — owning team and email for each service

Example (from svc-analytics.yaml):

openapi: 3.0.3
info:
  title: NovaTrek Analytics Service
  version: 1.3.0
  contact:
    name: NovaTrek Data & Insights Team
paths:
  /analytics/bookings:
    get:
      operationId: getBookingAnalytics
      summary: Get booking analytics for a period
      parameters:
        - $ref: '#/components/parameters/Period'
      responses:
        '200':
          description: Booking analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingAnalytics'

Why YAML?¶

YAML is the standard format for OpenAPI specifications because it offers the best balance of human readability and machine parseability for API contracts.

Readability¶

YAML uses significant whitespace instead of braces and brackets, making deeply nested API schemas easy to scan. Engineers can read and review a YAML spec in a pull request without tooling — compare:

# YAML — readable at a glance
BookingAnalytics:
  type: object
  properties:
    total_bookings:
      type: integer
      description: Total number of bookings in the period
    revenue:
      type: number
      format: double
      nullable: true

{
  "BookingAnalytics": {
    "type": "object",
    "properties": {
      "total_bookings": {
        "type": "integer",
        "description": "Total number of bookings in the period"
      },
      "revenue": {
        "type": "number",
        "format": "double",
        "nullable": true
      }
    }
  }
}

Both are valid OpenAPI — but the YAML version is roughly 40% fewer characters and far easier to diff in a code review.

References and reuse¶

YAML supports $ref pointers that let specs reference shared components without duplication. A parameter definition or schema defined once under components/ can be referenced across every endpoint:

parameters:
  - $ref: '#/components/parameters/Period'
  - $ref: '#/components/parameters/StartDate'

Tooling ecosystem¶

OpenAPI YAML files are consumed by a wide ecosystem of tools that would require manual effort to replicate:

Why Not Just Write Documentation?¶

Traditional API documentation is prose maintained by hand — it drifts from reality the moment a developer changes an endpoint without updating the docs. OpenAPI specs solve this by being:

The key insight: the spec IS the documentation. When a service changes, the spec is updated in the same pull request, and every downstream artifact (Swagger UI pages, sequence diagrams, microservice deep-dive pages, CALM topology) regenerates automatically.

How NovaTrek Uses These Specs¶

Architecture portal generation¶

The generate-microservice-pages.py script reads all 22 specs and produces:

1. Microservice deep-dive pages — one page per service with endpoint tables, schema details, and cross-service integration maps
2. PlantUML sequence diagrams — one diagram per endpoint (139 total), rendered as clickable SVGs with deep links to related services
3. Swagger UI pages — interactive API explorers served from portal/docs/services/api/

Solution design workflow¶

When architects design solutions for tickets, they propose changes to the OpenAPI spec, not to prose documentation. This means:

• Reviewers see the exact fields being added, modified, or removed
• Impact is traceable — every spec change maps to a ticket and a solution design
• Backward compatibility is assessed structurally (new required fields break consumers)

Cross-service integration¶

The specs define explicit contracts between services. When svc-check-in calls svc-guest-profiles, both sides reference the same schema definitions. This prevents:

• Schema drift — consumer and producer disagreeing on field types
• Shadow records — services inventing their own data models for data they do not own
• Undocumented dependencies — every integration point is visible in the spec

NovaTrek OpenAPI Conventions¶

Current Service Specs¶

All 22 service specifications live in architecture/specs/:

Browse the interactive API documentation in the Service Catalog, or explore the generated deep-dive pages under Microservices.