Swagger is for external-facing API docs — what API consumers see. Not for internal or service-to-service communication.
Pipeline (omni-docs-site)
.proto → OpenAPI 3.0 spec → MDX → Docusaurus site
.proto files are the source of truth. protoc-gen-openapiv2 (grpc-gateway) generates the OpenAPI spec automatically — no manual Swagger docs to maintain.
Key tools
- Buf — manages protobuf deps and runs codegen
- protoc-gen-openapiv2 —
.proto→ OpenAPI 3.0 - swagger2openapi — Swagger 2.0 → OpenAPI 3.0 if needed
See also
- codegen-multi-service — how .proto files are the source of truth across services
- json-tag — controlling field visibility in generated docs