# In web directory
pnpm add -D @hey-api/openapi-ts @apidevtools/swagger-cli @stoplight/spectral-cli

openapi: 3.1.0
info:
  title: VibeTunnel API
  version: 1.0.0
  description: Terminal sharing and remote access API
servers:
  - url: http://localhost:4020
    description: Local development server

{
  "scripts": {
    "generate:api": "openapi-ts -i openapi/openapi.yaml -o src/generated/api",
    "validate:api": "spectral lint openapi/openapi.yaml",
    "prebuild": "npm run generate:api"
  }
}

cd "$SRCROOT/../web" && \
swift-openapi-generator generate \
  openapi/openapi.yaml \
  --mode types \
  --mode client \
  --output-directory "$SRCROOT/Generated/OpenAPI"

# components/errors.yaml
ErrorResponse:
  type: object
  required: [error, timestamp]
  properties:
    error:
      type: string
      description: Human-readable error message
    code:
      type: string
      description: Machine-readable error code
      enum: [
        'INVALID_REQUEST',
        'NOT_FOUND',
        'UNAUTHORIZED',
        'SERVER_ERROR'
      ]
    timestamp:
      type: string
      format: date-time

# openapi/paths/git.yaml
/api/git/repository-info:
  get:
    operationId: getRepositoryInfo
    tags: [git]
    parameters:
      - name: path
        in: query
        required: true
        schema:
          type: string
    responses:
      '200':
        description: Repository information
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/GitRepositoryInfo'

# components/schemas.yaml
GitRepositoryInfo:
  type: object
  required: [isGitRepo, hasChanges, modifiedCount, untrackedCount, stagedCount, addedCount, deletedCount, aheadCount, behindCount, hasUpstream]
  properties:
    isGitRepo:
      type: boolean
    repoPath:
      type: string
    currentBranch:
      type: string
      nullable: true
    remoteUrl:
      type: string
      nullable: true
    githubUrl:
      type: string
      nullable: true
    hasChanges:
      type: boolean
    modifiedCount:
      type: integer
      minimum: 0
    untrackedCount:
      type: integer
      minimum: 0
    stagedCount:
      type: integer
      minimum: 0
    addedCount:
      type: integer
      minimum: 0
    deletedCount:
      type: integer
      minimum: 0
    aheadCount:
      type: integer
      minimum: 0
    behindCount:
      type: integer
      minimum: 0
    hasUpstream:
      type: boolean

// src/server/routes/git.ts
import { paths } from '../../generated/api';

type GitRepositoryInfo = paths['/api/git/repository-info']['get']['responses']['200']['content']['application/json'];

router.get('/git/repository-info', async (req, res) => {
  const response: GitRepositoryInfo = {
    isGitRepo: true,
    repoPath: result.repoPath,
    // ... ensure all required fields are included
  };
  res.json(response);
});

// Use generated types
import OpenAPIGenerated

let response = try await client.getRepositoryInfo(path: filePath)
let info = response.body.json // Fully typed!

SessionInfo:
  type: object
  required: [id, name, workingDir, status, createdAt, pid]
  properties:
    id:
      type: string
      format: uuid
    name:
      type: string
    workingDir:
      type: string
    status:
      type: string
      enum: [starting, running, exited]
    exitCode:
      type: integer
      nullable: true
    createdAt:
      type: string
      format: date-time
    lastActivity:
      type: string
      format: date-time
    pid:
      type: integer
      nullable: true
    command:
      type: array
      items:
        type: string

/api/sessions:
  get:
    operationId: listSessions
    responses:
      '200':
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SessionInfo'
  
  post:
    operationId: createSession
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSessionRequest'
    responses:
      '201':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionInfo'

// src/server/middleware/openapi-validator.ts
import { OpenAPIValidator } from 'express-openapi-validator';

export const openapiValidator = OpenAPIValidator.middleware({
  apiSpec: './openapi/openapi.yaml',
  validateRequests: true,
  validateResponses: true,
});

// Apply to routes
app.use('/api', openapiValidator);

// src/server/utils/validated-response.ts
export function validatedJson<T>(res: Response, data: T): void {
  if (process.env.NODE_ENV === 'development') {
    // Validate against OpenAPI schema
    validateResponse(res.req, data);
  }
  res.json(data);
}

# Add to package.json
"docs:api": "npx @redocly/cli build-docs openapi/openapi.yaml -o dist/api-docs.html"

// src/test/contract/git-api.test.ts
import { matchesSchema } from './schema-matcher';

test('GET /api/git/repository-info matches schema', async () => {
  const response = await request(app)
    .get('/api/git/repository-info')
    .query({ path: '/test/repo' });
    
  expect(response.body).toMatchSchema('GitRepositoryInfo');
});