Add OpenAPI documentation

Makefile

@@ -5,7 +5,7 @@ generate: patch-swagger-doc format
 	go mod vendor
 
 patch-swagger-doc: buf-gen
-	#./scripts/update_swagger.sh docs/openapiv2/apidocs.swagger.json
+	./scripts/update_swagger.sh docs/openapiv2/apidocs.swagger.json
 
 init-git-hooks:
 	git config --local core.hooksPath .githooks/

buf.gen.yaml

@@ -4,8 +4,19 @@ version: v2
 managed:
   enabled: true
   override:
+    # Standard go_package_prefix for our own proto files
     - file_option: go_package_prefix
       value: github.com/openkcm/api-sdk/proto
+    # Override for Google API dependencies to use the standard googleapis Go packages
+    # instead of generating them locally. This prevents import conflicts and uses
+    # the well-maintained googleapis packages from google.golang.org/genproto
+    - path: google/api
+      file_option: go_package
+      value: google.golang.org/genproto/googleapis/api/annotations;annotations
+    # Override for grpc-gateway OpenAPI v2 dependencies to use the standard grpc-gateway Go packages
+    - path: protoc-gen-openapiv2/options/annotations.proto
+      file_option: go_package
+      value: github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2/options;options
 plugins:
   - remote: buf.build/protocolbuffers/go
     out: proto
@@ -19,5 +30,11 @@ plugins:
     out: proto
     opt:
       - paths=source_relative
+  - remote: buf.build/grpc-ecosystem/openapiv2
+    out: docs/openapiv2
+    opt:
+      - allow_merge=true
+      - merge_file_name=apidocs
+      - allow_delete_body=true
 inputs:
   - directory: proto

buf.yaml

@@ -1,6 +1,9 @@
 version: v2
 modules:
   - path: proto
+deps:
+  - buf.build/googleapis/googleapis
+  - buf.build/grpc-ecosystem/grpc-gateway
 lint:
   use:
     - STANDARD