backend/scripts/swagger-drogon/README.md

swagger-drogon

swagger-drogon generates OpenAPI 3 documents from Drogon HttpController route macros.

The generator is intentionally hybrid:

• C++ route lists remain the source of truth for paths, methods and handlers.
• Adjacent openapi: comment blocks provide operation metadata.
• The generator infers simple path, query and JSON field usage from C++ code.
• An app contract file provides schemas that cannot be safely inferred from dynamic Json::Value and SQL result rows.
• Strict validation fails generation when an operation still has generic request or response bodies.

The contract file may be normal YAML when PyYAML is installed. Without external dependencies, the CLI also accepts JSON-compatible YAML, which is valid YAML syntax and keeps local CMake builds self-contained.

python3 -m swagger_drogon generate \
  --controllers ../../controllers \
  --sources ../../controllers ../../services \
  --contract ../../docs/openapi/visione.yaml \
  --out /tmp/visione.openapi.json