feat: generate additive OpenAPI 3.0.3 document

.gitattributes

@@ -1,4 +1,5 @@
 /docs/openapiv2/apidocs.swagger.json linguist-generated=true
+/docs/openapiv3/apidocs.openapi.json linguist-generated=true
 *.pb.go linguist-generated=true
 *.pb.*.go linguist-generated=true
 go.sum linguist-generated=true

.github/dependabot.yaml

@@ -11,6 +11,15 @@ updates:
         patterns:
           - "*"
 
+  - package-ecosystem: "gomod"
+    directory: "/tools/openapiv3"
+    schedule:
+      interval: "weekly"
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/review.yaml

@@ -30,10 +30,15 @@ jobs:
         with:
           fetch-depth: 0
       - uses: bufbuild/buf-setup-action@a47c93e0b1648d5651a065437926377d060baa99 # v1.50.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
+        with:
+          go-version: 1.26.6
+          cache-dependency-path: tools/openapiv3/go.sum
+      - run: make test-openapi-v3
       - name: "Generate OpenAPI & Diff"
         run: |
           make all
-          git diff --text --exit-code docs/openapiv2/apidocs.swagger.json proto/**/*.go
+          git diff --text --exit-code docs/openapiv2/apidocs.swagger.json docs/openapiv3/apidocs.openapi.json proto/**/*.go
 
   validate-openapi:
     runs-on: ubuntu-latest
@@ -45,3 +50,14 @@ jobs:
         with:
           definition-file: './docs/openapiv2/apidocs.swagger.json'
           fails-on: 1
+
+  validate-openapiv3:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+      - uses: swaggerexpert/apidom-validate@f839307deab4db59c7814834a2076d309e23b535 # v1
+        with:
+          definition-file: './docs/openapiv3/apidocs.openapi.json'
+          fails-on: 1

Makefile

@@ -1,11 +1,17 @@
-all: patch-swagger-doc format
+all: openapi-v3 format
 
 buf-gen: init-git-hooks
 	./buf.gen.yaml
 
 patch-swagger-doc: buf-gen
 	./scripts/update_swagger.sh docs/openapiv2/apidocs.swagger.json
 
+openapi-v3: patch-swagger-doc
+	cd tools/openapiv3 && go run .
+
+test-openapi-v3:
+	cd tools/openapiv3 && go test ./...
+
 format: buf-gen
 	buf format -w
 

README.md

@@ -55,13 +55,16 @@ may be overly strict. In those cases you can bypass it with `commit --no-verify`
     ```
 
 ### Generating OpenAPI Documentation
-To generate the OpenAPI documentation from the protobuf sources you can run the following commands:
+Generation produces both the finalized Swagger 2.0 document at
+`docs/openapiv2/apidocs.swagger.json` and an additive OpenAPI 3.0.3 document at
+`docs/openapiv3/apidocs.openapi.json`.
 
-> **Note**: You must have [jq](https://jqlang.github.io/jq/download/) installed to run the `format` step below
+> **Note**: You must have [jq](https://jqlang.github.io/jq/download/) and Go installed.
 
 ```bash
 ./buf.gen.yaml
 ./scripts/update_swagger.sh docs/openapiv2/apidocs.swagger.json
+(cd tools/openapiv3 && go run .)
 buf format -w
 ```
 
@@ -70,6 +73,11 @@ Or you can just use
 make
 ```
 
+The OpenAPI 3 document is deterministically converted from the finalized Swagger 2 document
+using the Go tool in `tools/openapiv3`.
+Existing SDK generation remains compatible with, and must continue to use,
+`docs/openapiv2/apidocs.swagger.json`.
+
 See [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md).
 
 ## Author