Add ConnectRPC Spec Definition for API Documentation

[devleejb]

What would you like to be added:

With the introduction of ConnectPRC, allowing REST API calls, it is necessary to document the specification. Using methods like OpenAPI to define the spec would enable the use of convenient GUI tools like Swagger.

Tools like protoc-gen-connect-openapi can automatically generate OpenAPI documentation from proto files.

The execution result is as shown below.

This will not only benefit REST API users but also aid in API development.

Why is this needed:

Documenting the ConnectRPC specification will provide better understanding and usability of the API, benefiting both users and developers alike.

[krapie]

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

[devleejb]

@krapie Does the documentation mean Yorkie Docs, right?

[krapie]

@devleejb Yes, just like Firebase.

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

[hackerwins]

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

[devleejb]

Can I try it?

[hackerwins]

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

[devleejb]

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).