chore: improve OpenAPI spec generation and add dev docs

Author: sallymoc

v2/Makefile

@@ -38,9 +38,10 @@ openapi-v3-gen:
 		query_services.proto
 	@echo "Cleaning up OpenAPI spec..."
 	cd "$(PROTO_DIR)" && \
-	yq -i 'del(.paths."/health")' query_services.openapi.yaml && \
-	yq -i '(.tags[] | select(.name == "ArchiveQueryService")).x-scalar-ignore = true' query_services.openapi.yaml && \
-	yq -i '(.paths[][].tags) -= ["ArchiveQueryService"]' query_services.openapi.yaml
+	yq -i --indent 4 'del(.paths."/health")' query_services.openapi.yaml && \
+	yq -i --indent 4 '(.tags[] | select(.name == "ArchiveQueryService")).x-scalar-ignore = true' query_services.openapi.yaml && \
+	yq -i --indent 4 '(.tags[] | select(.name == "Events (Beta)")).x-scalar-ignore = true' query_services.openapi.yaml && \
+	yq -i --indent 4 '(.paths[][].tags) -= ["ArchiveQueryService"]' query_services.openapi.yaml
 
 test-cover:
 	@echo "Performing Go cover test..."

v2/README.md

@@ -223,5 +223,16 @@ See [messages.proto](api/archive-query-service/v2/messages.proto)
 and [query_services.proto](api/archive-query-service/v2/query_services.proto) 
 for full details.
 
+## Regenerating protobuf and OpenAPI files
+
+Run `make` (or `make all`) to regenerate all protobuf and OpenAPI files.
+
+### Dev dependencies
+
+- `protoc` with Go plugins (`protoc-gen-go`, `protoc-gen-go-grpc`, `protoc-gen-grpc-gateway`)
+- `protoc-gen-openapi` (`go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest`)
+- `yq` - used for OpenAPI post-processing (`brew install yq` on macOS, `snap install yq` on Linux,
+  `choco install yq` on Windows, or [GitHub releases](https://github.com/mikefarah/yq/releases))
+
 ## Caching
 See [CACHE.md](CACHE.md) for details about enabling and using caching in Archive Query Service v2.