Add swagger-drogon generator

2026-06-03 01:52:43 +02:00
parent 1043768da7
commit 21883a4a8f
19 changed files with 1672 additions and 203 deletions
@@ -0,0 +1,26 @@
+# 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.
+
+```bash
+python3 -m swagger_drogon generate \
+  --controllers ../../controllers \
+  --sources ../../controllers ../../services \
+  --contract ../../docs/openapi/visione.yaml \
+  --out /tmp/visione.openapi.json
+```