openapi: 3.0.3
info:
  title: WIT Validator API
  description: |
    An API for validating WebAssembly Interface Type (WIT) files for syntax, structure, and best practices.
    This API checks various aspects of WIT files and returns detailed validation results.
  version: 0.1.0
  contact:
    email: brianpboynton@gmail.com
servers:
  - url: https://witgen.dev/api
    description: Production server
  - url: http://localhost:8787/api
    description: Local development server
paths:
  /health:
    get:
      summary: Health check
      description: Returns the health status of the API
      operationId: getHealth
      responses:
        '200':
          description: API is healthy
          content:
            text/plain:
              schema:
                type: string
                example: WIT Validator API is healthy
  /validate:
    post:
      summary: Validate WIT content
      description: Validates WIT content provided directly in the request body
      operationId: validateContent
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateContentRequest'
      responses:
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                type: string
                enum:
                  - Failed to read request body
                  - Invalid JSON body
                  - Missing 'content' field
                  - Content must be a string
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                type: string
                example: Invalid API key
  /validate-file:
    post:
      summary: Validate WIT file
      description: Validates a WIT file uploaded as form data
      operationId: validateFile
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: WIT file to validate
              required:
                - file
      responses:
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                type: string
                enum:
                  - Failed to parse form data
                  - No WIT file provided
                  - Failed to read file content
                  - File content is not valid UTF-8
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                type: string
                example: Invalid API key
components:
  schemas:
    ValidateContentRequest:
      type: object
      properties:
        content:
          type: string
          description: WIT file content to validate
          example: 'package example:math; interface calculator { add: func(a: u32, b: u32) -> u32; }'
      required:
        - content
    ValidationResult:
      type: object
      properties:
        valid:
          type: boolean
          description: Indicates if the WIT file is valid (no errors)
        errors:
          type: array
          items:
            type: string
          description: List of error messages
        warnings:
          type: array
          items:
            type: string
          description: List of warning messages
      example:
        valid: true
        errors: []
        warnings:
          - No world declaration found
          - Some statements may be missing semicolons
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: WITGEN_API_KEY
      in: header
      description: API key for authentication (e.g., test-api-key or wit_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX format)