Add ConnectRPC Spec Definition for API Documentation about yorkie HOT 7 CLOSED

@devleejb Yes, just like Firebase.

Edit: liveblocks API references seems to be the perfect example :)

from yorkie.

We can also refer to the following:

• https://liveblocks.io/docs/api-reference/rest-api-endpoints
• https://supabase.com/docs/guides/api#api-url-and-keys

from yorkie.

@devleejb Sure. You're a maintainer of this project.

from yorkie.

We might want to add this to our documentation for API usage 👍🏼

from yorkie.

Can I try it?

from yorkie.

I've made the modifications in buf.gen.yaml:

version: v1
plugins:
  - plugin: go
    out: api
    opt: paths=source_relative
  - plugin: connect-go
    out: api
    opt: paths=source_relative
  - plugin: connect-openapi
    out: api/docs
    opt:
      - base=api/docs/yorkie.base.yaml

The generated OpenAPI Spec can be served using the Swagger UI container, and I've added the corresponding command to the Makefile:

docker-swagger:
	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

As a result, when accessing the served documents, they will be displayed as shown in the image below:

However, adding the Authentication option in the connect-openapi library causes an error. I have reported this issue to the library's repository and will create a PR after resolving it.
Link to the GitHub Issue

After incorporating these changes, the following updates are required for the Yorkie Document:

• List additional endpoints to be added to the document.
• Write markdown documentation based on the OpenAPI Spec (considering automation).

from yorkie.

@krapie
Does the documentation mean Yorkie Docs, right?

from yorkie.