OpenAPI Specifications

OpenAPI Specifications

This directory contains OpenAPI (Swagger) 3.0 specifications for HeliosDB APIs.

Files

heliosdb-api.yaml

Main HeliosDB API specification covering:

• Query endpoints
• Health and status endpoints
• Database management
• Authentication

Usage

Interactive Documentation

Generate interactive Swagger UI documentation:

# Using Docker
docker run -p 8081:8080 -e SWAGGER_JSON=/api/heliosdb-api.yaml \
  -v $(pwd):/api swaggerapi/swagger-ui

# Or use the helper script
./scripts/api/serve-swagger.sh

Access at: http://localhost:8081

Generate Client SDKs

Use OpenAPI Generator to create client libraries:

# Python client
openapi-generator generate -i heliosdb-api.yaml -g python -o ../../../sdks/python

# TypeScript client
openapi-generator generate -i heliosdb-api.yaml -g typescript-fetch -o ../../../sdks/typescript

# Java client
openapi-generator generate -i heliosdb-api.yaml -g java -o ../../../sdks/java

Validate Specification

# Using OpenAPI CLI
openapi-cli validate heliosdb-api.yaml

# Using spectral
spectral lint heliosdb-api.yaml

Generate Static Documentation

# Using redoc-cli
redoc-cli bundle heliosdb-api.yaml -o ../../../docs/html/api-reference.html

# Using swagger-codegen
swagger-codegen generate -i heliosdb-api.yaml -l html2 -o ../../../docs/html/api

Specification Guidelines

When modifying OpenAPI specifications:

1. Follow OpenAPI 3.0.x conventions
2. Include comprehensive descriptions
3. Provide example requests/responses
4. Document all error codes
5. Use semantic versioning for API version
6. Run validation before committing

Related Documentation

• REST API Reference
• API Quick Reference
• Authentication Guide