Add Swagger Serving Command (#812)

This commit focuses on defining the ConnectRPC API Docs as an OpenAPI
Spec and includes adding a Swagger serving command. By converting the
API docs to an OpenAPI Spec, it enhances the readability, consistency,
and ease of use for developers utilizing the ConnectRPC API.

To access swagger, run `$ make swagger` and access to localhost:3000.

---------

Co-authored-by: Youngteac Hong <[email protected]>

Makefile

@@ -24,6 +24,7 @@ tools: ## install tools for developing yorkie
 	go install google.golang.org/protobuf/cmd/[email protected]
 	go install connectrpc.com/connect/cmd/[email protected]
 	go install github.com/golangci/golangci-lint/cmd/[email protected]
+	go install github.com/sudorandom/[email protected]
 
 proto: ## generate proto files
 	buf generate
@@ -64,6 +65,16 @@ docker: ## builds docker images with the current version and latest tag
 docker-latest: ## builds docker images with latest tag
 	docker buildx build --push --platform linux/amd64,linux/arm64,linux/386 -t yorkieteam/yorkie:latest .
 
+swagger: ## runs swagger-ui with the yorkie api docs
+	docker run -p 3000:8080 \
+  		-e URLS="[ \
+			{ url: 'docs/yorkie/v1/admin.openapi.yaml', name: 'Admin' }, \
+			{ url: 'docs/yorkie/v1/resources.openapi.yaml', name: 'Resources' }, \
+			{ url: 'docs/yorkie/v1/yorkie.openapi.yaml', name: 'Yorkie' }  \
+		]" \
+		-v `pwd`/api/docs:/usr/share/nginx/html/docs/ \
+  		swaggerapi/swagger-ui
+
 help:
 	@echo 'Commands:'
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "    %-20s %s\n", $$1, $$2}'

api/docs/yorkie.base.yaml

@@ -0,0 +1,18 @@
+openapi: 3.1.0
+info:
+  title: Yorkie
+  description: "Yorkie is an open source document store for building collaborative editing applications."
+  version: v0.4.14
+servers:
+  - url: https://api.yorkie.dev
+    description: Production server
+  - url: http://localhost:8080
+    description: Local server
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+security:
+  - ApiKeyAuth: [] # use the same name as under securitySchemes