Generate OpenAPI documentation (#353)

**What changed?**

We now generate openapi [v2 (swagger)](https://swagger.io/specification/v2/) and [v3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) specs as a part of proto compilation.

**Why?**

So that our customers can understand how to use our HTTP API

Author: tdeebswihart

.github/workflows/ci.yml

@@ -13,6 +13,8 @@ jobs:
         with:
           go-version: '^1.21'
       - uses: arduino/setup-protoc@v2
+      - name: 'Setup jq'
+        uses: dcarbone/install-jq-action@v2
       - run: make ci-build
       - name: Fail if the repo is dirty
         run: |

Makefile

@@ -1,12 +1,12 @@
 $(VERBOSE).SILENT:
 ############################# Main targets #############################
-ci-build: install proto
+ci-build: install proto http-api-docs
 
 # Install dependencies.
 install: grpc-install api-linter-install buf-install
 
 # Run all linters and compile proto files.
-proto: grpc
+proto: grpc http-api-docs
 ########################################################################
 
 ##### Variables ######
@@ -38,6 +38,9 @@ PROTO_IMPORTS = \
 	-I=$(PROTO_ROOT)
 PROTO_PATHS = paths=source_relative:$(PROTO_OUT)
 
+OAPI_OUT := openapi
+OAPI3_PATH := .components.schemas.Payload
+
 $(PROTO_OUT):
 	mkdir $(PROTO_OUT)
 
@@ -46,23 +49,44 @@ grpc: buf-lint api-linter buf-breaking clean go-grpc fix-path
 
 go-grpc: clean $(PROTO_OUT)
 	printf $(COLOR) "Compile for go-gRPC..."
-	$(foreach PROTO_DIR,$(PROTO_DIRS),\
-		protoc --fatal_warnings $(PROTO_IMPORTS) \
-		 	--go_out=$(PROTO_PATHS) \
-            --grpc-gateway_out=allow_patch_feature=false,$(PROTO_PATHS)\
-			--doc_out=html,index.html,source_relative:$(PROTO_OUT) \
-		$(PROTO_DIR)*.proto;)
+	protogen \
+		--root=$(PROTO_ROOT) \
+		--output=$(PROTO_OUT) \
+		--exclude=internal \
+		--exclude=proto/api/google \
+		-I $(PROTO_ROOT) \
+		-p go-grpc_out=$(PROTO_PATHS) \
+		-p grpc-gateway_out=allow_patch_feature=false,$(PROTO_PATHS) \
+		-p doc_out=html,index.html,source_relative:$(PROTO_OUT) \
+		-p openapi_out=$(OAPI_OUT) \
+		-p openapi_opt=enum_type=string \
+		-p openapiv2_out=openapi \
+        -p openapiv2_opt=allow_merge=true,merge_file_name=openapiv2
 
 fix-path:
 	mv -f $(PROTO_OUT)/temporal/api/* $(PROTO_OUT) && rm -rf $(PROTO_OUT)/temporal
 
+# We need to rewrite bits of this to support our shorthand payload format
+# We use both yq and jq here as they preserve comments and the ordering of the original
+# document
+http-api-docs: go-grpc
+	jq --rawfile desc $(OAPI_OUT)/payload_description.txt < $(OAPI_OUT)/openapiv2.swagger.json '.definitions.v1Payload={description: $$desc}' > $(OAPI_OUT)/v2.tmp
+	mv -f $(OAPI_OUT)/v2.tmp $(OAPI_OUT)/openapiv2.json
+	rm -f $(OAPI_OUT)/openapiv2.swagger.json
+	DESC=$$(cat $(OAPI_OUT)/payload_description.txt) yq e -i '$(OAPIV3_PATH).description = strenv(DESC) | del($(OAPI3_PATH).type) | del($(OAPI3_PATH).properties)' $(OAPI_OUT)/openapi.yaml
+	mv $(OAPI_OUT)/openapi.yaml $(OAPI_OUT)/openapiv3.yaml
+
 ##### Plugins & tools #####
 grpc-install:
 	@printf $(COLOR) "Install/update protoc and plugins..."
+	@go install go.temporal.io/api/cmd/protogen@latest
 	@go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
 	@go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
 	@go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
 	@go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest
+	@go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
+	@go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest
+	@go install github.com/mikefarah/yq/v4@latest
 
 api-linter-install:
 	printf $(COLOR) "Install/update api-linter..."

README.md

@@ -1,5 +1,7 @@
 # Temporal proto files  
 
+This repository contains both the protobuf descriptors and OpenAPI documentation for the Temporal platform.
+
 ## How to use
 
 Install as git submodule to the project.