Skip to main content

OpenAPI Spec — Implementation Guide

Practical implementation patterns to ensure OpenAPI specs are safe for code generation and sharing.

Core recommendations​

  • Strip audit and internal fields from the spec on import and export
  • Validate with a strict OpenAPI schema validator (3.x) and reject nonconformant files
  • Normalize schema types (avoid vendor-specific extensions where possible)

Backend hooks​

  • During import: use OpenAPISpecUtils.filterIgnoredFields and schema validation
  • When storing: persist only sanitized spec JSON/YAML
  • When generating: pass sanitized spec to ThorAPI codegen

Frontend tips​

  • Always display a cleaned preview (filterIgnoredFields) before commit
  • Show warnings when user tries to export raw spec containing internal fields

See also: OAS Spec Quick Reference