Skip to content

SPOT Contracts Documentation

Single source of truth for all SPOT Platform API contracts and generated SDKs.

This repository centralizes OpenAPI specifications and Python interface definitions for the entire SPOT ecosystem, automatically generating and publishing SDKs for Python and TypeScript with comprehensive documentation.

Quick Start

No local dependencies required - everything runs in Docker containers:

# Build docker containers
make build

# Validate OpenAPI specifications
make validate

# Generate both SDKs
make generate

# Run comprehensive tests
make test

# Generate documentation site
make docs

# See full list of commands
make help

Architecture

The SPOT Contracts repository follows a simple architecture:

spot-sdk/
├── docs/                 # Documentation (this directory)
├── openapi/              # OpenAPI 3.0 specifications  
│   └── api-gateway.yaml  # Unified API Gateway
├── interfaces/           # Python interface models (Pydantic v2)
│   ├── email.py          # Email data models
│   ├── analyzer.py       # Analyzer interfaces  
│   └── results.py        # Analysis result models
├── sdk/                  # Generated SDKs
│   ├── python/           # Python SDK with Poetry
│   └── typescript/       # TypeScript SDK with NPM
├── tests/                # Contract validation tests (97%+ coverage)
└── scripts/              # Automation scripts

Core Features

  • Automated SDK Generation - Python and TypeScript SDKs from OpenAPI specs
  • Private Registry Publishing - GitLab PyPI and NPM registries
  • High Test Coverage - 97%+ coverage with comprehensive validation
  • Docker-First Development - No local dependencies required
  • CI/CD Pipeline - Tag-based publishing with zero manual steps
  • Interactive Documentation - API specs with Swagger UI integration

Available Commands

Command Description
Development
make help Show all available commands with descriptions
make validate Validate OpenAPI specifications
make generate Generate both Python and TypeScript SDKs
make test Run contract validation tests (Docker-based)
make shell Enter interactive development container
Documentation
make docs Generate complete documentation site
make docs-serve Serve documentation locally on port 8005
Publishing
make publish-python Publish Python SDK to GitLab Registry
make publish-typescript Publish TypeScript SDK to GitLab Registry

Environment Configuration

Create .env file for local development:

# Copy example configuration
cp .env.example .env

# Configure your GitLab settings

CI_PROJECT_ID=303
GITLAB_TOKEN=glpat-your-token-here
GITLAB_CA_CERT=certs/gitlab-ca.crt  # For private GitLab instances

Contributing

Development Workflow

  1. Update OpenAPI specs in openapi/ directory
  2. Validate changes: make validate
  3. Generate SDKs: make generate
  4. Run tests: make test
  5. Generate docs: make docs
  6. Preview locally: make docs-serve
  7. Commit changes

Working with the SPOT Platform?

SPOT Project | Issues | Documentation