ClickHouse OpenAPI
Auto-generated OpenAPI docs from ClickHouse query definitions
When you define ClickHouse queries with hypequery, the OpenAPI specification is generated automatically. Request validation, response schemas, and Swagger UI — all derived from your Zod input schemas and ClickHouse-generated output types. No manual documentation step.
Spec format
OpenAPI 3.0
Source
Derived from query types
UI
Swagger included
Analytics APIs are rarely documented
Internal ClickHouse analytics APIs almost never have OpenAPI docs — the team writes the endpoints, frontend developers guess the shape from network logs, and breaking changes get discovered at runtime rather than compile time.
Writing OpenAPI specs by hand drifts from the implementation
When you hand-write OpenAPI YAML alongside your ClickHouse query code, the two drift immediately. The spec says one shape, the query returns another — and the gap grows with every schema change.
Client generation requires accurate specs
Tools like openapi-typescript and openapi-generator can generate fully typed frontend clients from your API spec — but only if the spec is accurate and up to date. A hand-maintained spec is never fully trustworthy.
How it works
The spec is derived from types, not written by hand
When you define a query with hypequery, the input schema comes from Zod and the output schema comes from the ClickHouse-generated types. @hypequery/serve reads both and generates the OpenAPI spec automatically — it is always in sync with the actual implementation.
- Request body schema derived from your Zod input definition
- Response schema derived from ClickHouse-generated TypeScript types
- Full OpenAPI 3.0 spec available at /openapi.json
- Interactive Swagger UI available at /docs
- Spec updates automatically when query definitions change
Query definition
Input and output types become the OpenAPI spec
The Zod schema defines the request body. The ClickHouse return type defines the response. hypequery generates the OpenAPI spec from both — no manual step.
Generated output
The OpenAPI spec reflects your real types, always
The generated spec is derived directly from the types in your codebase — not from a separate documentation layer. When you change a query input or the ClickHouse schema changes, the spec updates automatically on the next generate run.
This makes client generation reliable. Use openapi-typescript to generate a fully typed frontend client from the spec — knowing it reflects the actual query shapes.
See the REST API guide for the full serve() setup, and the React hooks guide for consuming the typed endpoints in dashboard components.
Generated spec
OpenAPI output for the activeUsers query
The spec reflects the Zod input schema and the ClickHouse output types exactly. Use it to generate typed clients, share with third-party consumers, or power Swagger UI.
Why teams search for this
Common implementation questions this page should solve
ClickHouse API documentation
Most ClickHouse analytics APIs have no documentation because hand-writing OpenAPI specs is too slow. hypequery generates the spec automatically from your query type definitions — no manual documentation step.
Generate OpenAPI from ClickHouse TypeScript
If your ClickHouse analytics are served as HTTP endpoints, hypequery can generate the OpenAPI spec from your TypeScript query definitions. Input validation, response types, and Swagger UI all included.
ClickHouse API client generation
With an accurate OpenAPI spec from hypequery, you can generate fully typed frontend clients using openapi-typescript or similar tools. The spec is always in sync with the implementation.
ClickHouse Swagger UI
hypequery serves an interactive Swagger UI at /docs automatically. Your analytics endpoints are explorable and testable from the browser without any additional tooling setup.
Further reading
Go deeper with comparison posts and implementation guides
ClickHouse REST API
The full guide to serving ClickHouse queries as typed HTTP endpoints with @hypequery/serve.
Open guide
ClickHouse Query Builder
The query definitions that drive the OpenAPI spec and the HTTP endpoints.
Open guide
ClickHouse React hooks
Consume your typed REST endpoints as React hooks for dashboard components.
Open guide
ClickHouse schema generation
How the TypeScript types are generated from your ClickHouse schema — the source of the response schemas.
Open guide
Next step
Get OpenAPI docs from your first ClickHouse query
Define a query, serve it with @hypequery/serve, and visit /openapi.json. The spec is generated immediately from your input and output types.