OpenAPI

Hyperterse automatically generates OpenAPI 3.0 specifications from your query definitions. This enables integration with API clients, testing tools, and documentation platforms.

Accessing OpenAPI specs

Runtime endpoint

The OpenAPI specification is available at /docs:

curl http://localhost:8080/docs

This returns a complete OpenAPI 3.0 JSON specification.

View in browser

Open http://localhost:8080/docs in your browser to see the raw specification, or use a tool like Swagger UI.

Generated specification

For each query, Hyperterse generates:

Path: /query/{query-name}
Method: POST
Request Schema: Based on input definitions
Response Schema: Based on data definitions
Description: From query description

Example

Given this query:

1
queries:
2
  get-user-by-id:
3
    use: main_db
4
    description: 'Retrieve a user by their unique ID'
5
    statement: 'SELECT id, name, email FROM users WHERE id = {{ inputs.userId }}'
6
    inputs:
7
      userId:
8
        type: int
9
        description: 'Unique user identifier'

Hyperterse generates:

1
{
2
  "openapi": "3.0.0",
3
  "info": {
4
    "title": "Hyperterse API",
5
    "version": "1.0.0"
6
  },
7
  "paths": {
8
    "/query/get-user-by-id": {
9
      "post": {
10
        "summary": "Retrieve a user by their unique ID",
11
        "requestBody": {
12
          "required": true,
13
          "content": {
14
            "application/json": {
15
              "schema": {
16
                "type": "object",
17
                "required": ["userId"],
18
                "properties": {
19
                  "userId": {
20
                    "type": "integer",
21
                    "description": "Unique user identifier"
22
                  }
23
                }
24
              }
25
            }
26
          }
27
        },
28
        "responses": {
29
          "200": {
30
            "description": "Successful response",
31
            "content": {
32
              "application/json": {
33
                "schema": {
34
                  "type": "object",
35
                  "properties": {
36
                    "success": { "type": "boolean" },
37
                    "error": { "type": "string" },
38
                    "results": {
39
                      "type": "array",
40
                      "items": {
41
                        "type": "object",
42
                        "properties": {
43
                          "id": { "type": "integer" },
44
                          "name": { "type": "string" },
45
                          "email": { "type": "string" }
46
                        }
47
                      }
48
                    }
49
                  }
50
                }
51
              }
52
            }
53
          }
54
        }
55
      }
56
    }
57
  }
58
}

Using with swagger UI

Docker

Run Swagger UI pointing to your Hyperterse server:

docker run -p 8081:8080 \
  -e SWAGGER_JSON_URL=http://host.docker.internal:8080/docs \
  swaggerapi/swagger-ui

Open http://localhost:8081 to browse your API.

Embedded

You can also embed the OpenAPI spec in your own Swagger UI deployment.

Type mappings

Hyperterse types map to OpenAPI types:

Hyperterse	OpenAPI
`string`	`string`
`int`	`integer` (format: `int64`)
`float`	`number` (format: `double`)
`boolean`	`boolean`
`uuid`	`string` (format: `uuid`)
`datetime`	`string` (format: `date-time`)

API client generation

Use the OpenAPI spec to generate typed API clients:

JavaScript/TypeScript

npx openapi-typescript http://localhost:8080/docs --output api.ts

Python

# Using openapi-python-client
openapi-python-client generate --url http://localhost:8080/docs

Go

# Using oapi-codegen
oapi-codegen -package api http://localhost:8080/docs > api.go

Response format

All query endpoints return a consistent format:

1
{
2
  "success": true,
3
  "error": "",
4
  "results": [...]
5
}

This is documented in the OpenAPI spec for all endpoints.

Error responses

Error responses follow the same structure:

1
{
2
  "success": false,
3
  "error": "validation error for field 'userId': required input is missing",
4
  "results": []
5
}