How actinia-org/actinia-api works
Project type and purpose
• This repository is an open-source tool—a centralized collector and publisher of OpenAPI (Swagger2) documentation for the actinia‐core service and its plugins.
• It does not contain runtime application logic; it bundles YAML/Python swagger definitions, builds distributable packages (Python wheel, source), and publishes them independently of the code repositories.
File structure
• Top‐level “src/actinia_api/swagger2/actinia_core/apidocs” and “…/schemas” houses all REST API endpoint definitions and JSON schemas.
• Project root contains configuration for Python packaging (pyproject.toml, setup.py, setup.cfg), black/flake8 CI, and Docker‐based release tooling under “docker/release”.
• GitHub workflows for linting (black.yml), static analysis (flake8.yml), and automated Python package publishing (python-publish.yml).
README for additional insights
• Confirms the migration goal: decouple API docs versioning from code.
• Highlights ongoing migration work: some docs still live in source code repos, but this repo is the future canonical home.
a. Main components
– Developer Workstation (local dev tools)
– GitHub Repository (acts as source of truth)
– GitHub Actions CI pipelines (lint, format, test, package)
– Docker Build Environment (for release images)
– PyPI Registry (Python package distribution)
– Downstream Consumers (services or clients that import actinia_api docs)
b. Relationships and data flow
– Developer pushes commits → GitHub Repo
– Push triggers GitHub Actions:
• black & flake8 run over src/
• on tag → python-publish builds wheel/sdist → pushes to PyPI
• docker/release pipeline builds Docker image → pushes to Docker registry (optional)
– Consumers fetch actinia_api from PyPI (or Docker image) → integrate swagger definitions into documentation tools or API gateways
c. Architectural patterns and design principles
– Separation of concerns: docs are versioned separately from implementation
– CI/CD-driven packaging and deployment
– Modularity in swagger definitions (one file per endpoint group)
d. Key technologies and frameworks
– Python packaging: setuptools (setup.py), pyproject.toml
– Swagger2/OpenAPI for REST definitions
– Docker for release image management
– GitHub Actions for CI/CD
– Black and Flake8 for code style and linting