feat: generate additive OpenAPI 3.0.3 document

[Siddhant-K-code]

Summary

• Generate docs/openapiv3/apidocs.openapi.json deterministically from the finalized Swagger 2 artifact.
• Pin swagger2openapi@7.0.8 and guard conversion with strict shape, parity, reference, example, service, and response validation.
• Extend generated-file freshness and ApiDOM validation for OAS3 while retaining existing OAS2 validation.

Current generation flow

Protobuf sources and existing grpc-gateway OAS2 annotations
  → grpc-gateway OpenAPI v2 generator
  → scripts/update_swagger.sh semantic cleanup
  → docs/openapiv2/apidocs.swagger.json
  → deterministic OAS2-to-OAS3 conversion
  → docs/openapiv3/apidocs.openapi.json

The finalized OAS2 artifact remains the compatibility source for existing consumers. OAS3 is an additive, generated representation of that same API surface.

Why not generate OAS3 directly from proto?

The current protobuf sources express API documentation primarily through grpc.gateway.protoc_gen_openapiv2.options.* annotations. A native OAS3 generator does not interpret all of that OAS2-specific metadata.

A direct generation candidate was evaluated, but its output materially differed from the current API contract:

• 25 operations instead of 24, including the unimplemented UpdateStore operation
• 97 schemas instead of 114
• rewritten operation IDs and lost custom tags
• missing custom responses, descriptions, and all existing examples
• request bodies that included fields already represented as path parameters

Post-processing cannot safely restore metadata that the native generator never emitted. Moving to native proto-to-OAS3 generation therefore requires a separate migration of the protobuf documentation annotations, visibility behavior, response metadata, examples, service merging, and request-body semantics, followed by the same parity validation introduced here.

This PR uses conversion as a compatibility-preserving bridge and does not prevent a future native OAS3 migration.

Compatibility

• docs/openapiv2/apidocs.swagger.json remains byte-identical and continues to be the SDK generator input.
• No protobuf APIs, generated Go, operation IDs, tags, examples, response codes, servers, or security policy are changed.
• SDK adoption of OAS3 remains separate future work.

Maintenance model

• Swagger 2 remains the compatibility artifact while existing SDK and tooling consumers depend on it.
• OpenAPI 3 is generated automatically from the finalized Swagger 2 artifact as part of make all; contributors do not maintain two specifications manually.
• Freshness and parity checks prevent the generated artifacts from drifting.
• Retiring Swagger 2 requires a separate consumer migration and deprecation decision.

Validation

• npm audit --audit-level=low
• make all
• buf lint
• buf format -d --exit-code
• cd proto && go test ./...
• ApiDOM validation for OAS2 and OAS3
• SDK preprocessing parity for standard, streamed, and non-streamed targets

Scope

This PR adds a documentation-oriented OAS3 artifact only. Server/environment metadata, authentication policy, downstream documentation navigation, specification consolidation, and SDK migration are intentionally out of scope.

Follow-ups

• Configure playground server/environment choices in the documentation layer, where deployment context is known.
• Define Mintlify API navigation grouping in the documentation configuration rather than changing canonical API tags.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​swagger2openapi@​7.0.8

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

• npm/es6-promise@3.3.1
• npm/yargs@17.7.3

View full report

[Siddhant-K-code]

@SocketSecurity ignore npm/es6-promise@3.3.1

Reviewed as an acceptable risk for this PR. This transitive dependency is used only by node-readfiles, which is imported by swagger2openapi’s separate validator CLI and is not loaded by our convertObj library path. The flagged file is the package’s documented minified browser bundle; it matches the package’s declared upstream source commit byte-for-byte and includes source maps with the original sources. The lockfile integrity matches the npm registry, registry signatures verify, npm audit reports no vulnerabilities, and the package has no install lifecycle hooks.

[Siddhant-K-code]

@SocketSecurity ignore npm/yargs@17.7.3

Reviewed as an acceptable risk for this PR. yargs is used by swagger2openapi and oas-resolver CLI entrypoints, not by the convertObj library path used here. The flagged one-line CJS bundle is generated build output that reproduces byte-for-byte from the package’s declared upstream source commit. Static review found no dynamic evaluation, process spawning, network access, or filesystem writes in the bundle. The lockfile integrity matches the npm registry, registry signatures verify, npm audit reports no vulnerabilities, and the package has no install lifecycle hooks.