SnitchItaly/backend
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Add swagger-drogon generator

Browse Source
This commit is contained in:
gabdevele
2026-06-03 01:52:43 +02:00 Unverified
parent 1043768da7
commit 21883a4a8f
19 changed files with 1672 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+13 -9
View File
@@ -6,7 +6,9 @@
- `repositories/`: database helpers and migrations.
- `common/`: reusable HTTP, auth, crypto, email and validation utilities.
- `migrations/`: versioned SQL files.
- `scripts/generate_openapi.py`: OpenAPI generator.
- `scripts/swagger-drogon/`: OpenAPI generator package.
- `scripts/generate_openapi.py`: compatibility wrapper for the generator.
- `docs/openapi/`: app-specific OpenAPI schema registry.
- `scripts/lab/`: local Streamlit frontend for visual endpoint testing.
- `docs/`: product, API, schema and milestone documentation.
@@ -29,15 +31,17 @@ available through OpenSSL, which is already a Drogon dependency in this project.
Legacy `sha256$` password hashes are rejected instead of silently accepted.
## OpenAPI Generation
`scripts/generate_openapi.py` scans Drogon `ADD_METHOD_TO` route macros and the
adjacent `openapi:` metadata blocks in `controllers/*.h`, then generates
`build/openapi/visione.openapi.json`.
`scripts/swagger-drogon/` scans Drogon `ADD_METHOD_TO` route macros and the
adjacent `openapi:` metadata blocks in `controllers/*.h`. It also inspects
controller/service `.cc` files for simple query, JSON field and response field
patterns, then merges the app-specific registry in `docs/openapi/visione.yaml`.
The CMake `openapi` target writes `build/openapi/visione.openapi.json`.
This is a contract-last generator: the source of truth is the C++ controller
route list, not a manually maintained static Swagger document. The current tool
generates paths, methods, path parameters, summaries, descriptions, auth hints
and common JSON or multipart request bodies. Generation fails if a route lacks
metadata.
This is a hybrid generator: C++ is the source of truth for routes and metadata,
while YAML provides schemas that cannot be safely inferred from dynamic
`Json::Value` payloads and raw SQL result rows. Generation fails if a route lacks
metadata, has unresolved schema refs, emits `/photos`, or leaves operation
request/response schemas as generic objects.
## Visione Lab
`scripts/lab/` is a Streamlit dev frontend for visual endpoint testing. It is