#OpenAPI overview

hclapi statically analyzes your manifest Abstract Syntax Tree (AST) at boot time to compile a strict, 100% compliant OpenAPI 3.1 specification.

You don't need to maintain separate YAML files, write code annotations, or run external generators. The HCL manifest is the API contract.

Additionally, no hidden routes are mounted behind your back. If an OpenAPI endpoint or interactive documentation portal is served by your application, it's explicitly declared as an endpoint block.

#What is automatically derived

Because hclapi manifests are statically typed, the compiler maps every part of your manifest directly into OpenAPI 3.1:

#Explicit endpoint declaration

You control the exact paths, renderers, and access guards for your documentation by declaring explicit endpoint blocks:

# Public interactive documentation portal using Scalar
endpoint "GET /docs" {
  description = "Public interactive API documentation."
  auth        = []

  openapi {
    ui = "scalar"
  }
}

# Raw OpenAPI 3.1 JSON specification
endpoint "GET /openapi.json" {
  openapi {
    format = "json"
  }
}

# Raw OpenAPI 3.1 YAML specification
endpoint "GET /openapi.yaml" {
  openapi {
    format = "yaml"
  }
}

# Internal Swagger UI protected by Basic Auth
endpoint "GET /admin/swagger" {
  description = "Internal Swagger UI for engineering team."
  auth        = [auth.basic_admin]

  openapi {
    ui = "swagger"
  }
}

#Static CLI export

You can export the compiled OpenAPI document directly from your terminal or CI/CD pipeline without starting the HTTP server:

# Export JSON to stdout
hclapi openapi -c ./api

# Export JSON to file
hclapi openapi -c ./api -o ./openapi.json

# Export YAML to stdout
hclapi openapi -c ./api --format=yaml

# Export YAML to file
hclapi openapi -c ./api --format=yaml -o ./openapi.yaml

The exported specification can be fed directly into an OpenAPI SDK generator or client generator.

#SDK options