FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

feat: generate additive OpenAPI 3.0.3 document by Siddhant-K-code · Pull Request #259 · openfga/api · GitHub

/ api Public

feat: generate additive OpenAPI 3.0.3 document - #259

Draft
Siddhant-K-code wants to merge 1 commit into
mainfrom
siddhant-k-code-implement-openapi-v3
ConversationCommits (1)ChecksFiles changed
Draft

feat: generate additive OpenAPI 3.0.3 document#259
Siddhant-K-code wants to merge 1 commit into
mainfrom
siddhant-k-code-implement-openapi-v3

Conversation

Siddhant-K-code commented Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

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.

feat: generate additive OpenAPI v3 document
c963bd2 
Convert the finalized Swagger 2 artifact to a deterministic OpenAPI 3.0.3 document with strict parity validation and additive CI coverage.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

coderabbitai Bot commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

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

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

socket-security Bot commented Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown

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 Bot commented Aug 27, 2026 •
edited
Loading

Copy link
Copy Markdown

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 commented Aug 27, 2026

Copy link
Copy Markdown
Member Author

@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 commented Aug 27, 2026

Copy link
Copy Markdown
Member Author

@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.

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot will automatically review once the pull request is marked ready for review

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

Back | FazBrowse Home | New Git URL