chore: update services comment

2025-06-05 22:09:59 +02:00 · 2024-02-01 21:26:09 +08:00
parent f6f193af2d
commit c342c464a2
17 changed files with 231 additions and 27 deletions
--- a/api/v2/apidocs.swagger.md
+++ b/api/v2/apidocs.swagger.md
@@ -103,6 +103,10 @@ GetAuthStatus returns the current auth status of the user.
 ### /api/v2/inboxes

 #### GET
+##### Summary
+
+ListInboxes lists inboxes for a user.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -119,6 +123,10 @@ GetAuthStatus returns the current auth status of the user.
 ### /v2/inboxes

 #### PATCH
+##### Summary
+
+UpdateInbox updates an inbox.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -135,6 +143,10 @@ GetAuthStatus returns the current auth status of the user.
 ### /v2/{name}

 #### DELETE
+##### Summary
+
+DeleteInbox deletes an inbox.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -434,6 +446,10 @@ ExportMemos exports memos.
 ### /api/v2/resources

 #### GET
+##### Summary
+
+ListResources lists all resources.
+
 ##### Responses

 | Code | Description | Schema |
@@ -442,6 +458,10 @@ ExportMemos exports memos.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### POST
+##### Summary
+
+CreateResource creates a new resource.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -461,6 +481,10 @@ ExportMemos exports memos.
 ### /api/v2/resources/{id}

 #### GET
+##### Summary
+
+GetResource returns a resource by id.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -475,6 +499,10 @@ ExportMemos exports memos.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### DELETE
+##### Summary
+
+DeleteResource deletes a resource by id.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -491,6 +519,10 @@ ExportMemos exports memos.
 ### /api/v2/resources/{name}

 #### GET
+##### Summary
+
+GetResourceByName returns a resource by name.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -507,6 +539,10 @@ ExportMemos exports memos.
 ### /api/v2/resources/{resource.id}

 #### PATCH
+##### Summary
+
+UpdateResource updates a resource.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -527,6 +563,10 @@ ExportMemos exports memos.
 ### /api/v2/tags

 #### GET
+##### Summary
+
+ListTags lists tags.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -541,6 +581,10 @@ ExportMemos exports memos.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### DELETE
+##### Summary
+
+DeleteTag deletes a tag.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -556,6 +600,10 @@ ExportMemos exports memos.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### POST
+##### Summary
+
+UpsertTag upserts a tag.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -572,6 +620,10 @@ ExportMemos exports memos.
 ### /api/v2/tags/suggestion

 #### GET
+##### Summary
+
+GetTagSuggestions gets tag suggestions from the user's memos.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -588,6 +640,10 @@ ExportMemos exports memos.
 ### /api/v2/tags:batchUpsert

 #### POST
+##### Summary
+
+BatchUpsertTag upserts multiple tags.
+
 ##### Responses

 | Code | Description | Schema |
@@ -598,6 +654,11 @@ ExportMemos exports memos.
 ### /api/v2/tags:rename

 #### PATCH
+##### Summary
+
+RenameTag renames a tag.
+All related memos will be updated.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -731,6 +792,10 @@ DeleteUserAccessToken deletes an access token for a user.
 ### /api/v2/{name}/setting

 #### GET
+##### Summary
+
+GetUserSetting gets the setting of a user.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -747,6 +812,10 @@ DeleteUserAccessToken deletes an access token for a user.
 ### /api/v2/{setting.name}

 #### PATCH
+##### Summary
+
+UpdateUserSetting updates the setting of a user.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -808,6 +877,10 @@ CreateUser creates a new user.
 ### /api/v2/webhooks

 #### GET
+##### Summary
+
+ListWebhooks returns a list of webhooks.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -822,6 +895,10 @@ CreateUser creates a new user.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### POST
+##### Summary
+
+CreateWebhook creates a new webhook.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -838,6 +915,10 @@ CreateUser creates a new user.
 ### /api/v2/webhooks/{id}

 #### GET
+##### Summary
+
+GetWebhook returns a webhook by id.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -852,6 +933,10 @@ CreateUser creates a new user.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### DELETE
+##### Summary
+
+DeleteWebhook deletes a webhook by id.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -868,6 +953,10 @@ CreateUser creates a new user.
 ### /api/v2/webhooks/{webhook.id}

 #### PATCH
+##### Summary
+
+UpdateWebhook updates a webhook.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -888,6 +977,10 @@ CreateUser creates a new user.
 ### /api/v2/workspace/profile

 #### GET
+##### Summary
+
+GetWorkspaceProfile returns the workspace profile.
+
 ##### Responses

 | Code | Description | Schema |
@@ -896,6 +989,10 @@ CreateUser creates a new user.
 | default | An unexpected error response. | [googlerpcStatus](#googlerpcstatus) |

 #### PATCH
+##### Summary
+
+UpdateWorkspaceProfile updates the workspace profile.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
@@ -915,6 +1012,10 @@ CreateUser creates a new user.
 ### /v2/activities

 #### GET
+##### Summary
+
+GetActivity returns the activity with the given id.
+
 ##### Parameters

 | Name | Located in | Description | Required | Schema |
--- a/api/v2/apidocs.swagger.yaml
+++ b/api/v2/apidocs.swagger.yaml
@@ -130,6 +130,7 @@ paths:
        - AuthService
  /api/v2/inboxes:
    get:
+      summary: ListInboxes lists inboxes for a user.
      operationId: InboxService_ListInboxes
      responses:
        "200":
@@ -503,6 +504,7 @@ paths:
        - MemoService
  /api/v2/resources:
    get:
+      summary: ListResources lists all resources.
      operationId: ResourceService_ListResources
      responses:
        "200":
@@ -516,6 +518,7 @@ paths:
      tags:
        - ResourceService
    post:
+      summary: CreateResource creates a new resource.
      operationId: ResourceService_CreateResource
      responses:
        "200":
@@ -548,6 +551,7 @@ paths:
        - ResourceService
  /api/v2/resources/{id}:
    get:
+      summary: GetResource returns a resource by id.
      operationId: ResourceService_GetResource
      responses:
        "200":
@@ -567,6 +571,7 @@ paths:
      tags:
        - ResourceService
    delete:
+      summary: DeleteResource deletes a resource by id.
      operationId: ResourceService_DeleteResource
      responses:
        "200":
@@ -587,6 +592,7 @@ paths:
        - ResourceService
  /api/v2/resources/{name}:
    get:
+      summary: GetResourceByName returns a resource by name.
      operationId: ResourceService_GetResourceByName
      responses:
        "200":
@@ -606,6 +612,7 @@ paths:
        - ResourceService
  /api/v2/resources/{resource.id}:
    patch:
+      summary: UpdateResource updates a resource.
      operationId: ResourceService_UpdateResource
      responses:
        "200":
@@ -651,6 +658,7 @@ paths:
        - ResourceService
  /api/v2/tags:
    get:
+      summary: ListTags lists tags.
      operationId: TagService_ListTags
      responses:
        "200":
@@ -672,6 +680,7 @@ paths:
      tags:
        - TagService
    delete:
+      summary: DeleteTag deletes a tag.
      operationId: TagService_DeleteTag
      responses:
        "200":
@@ -697,6 +706,7 @@ paths:
      tags:
        - TagService
    post:
+      summary: UpsertTag upserts a tag.
      operationId: TagService_UpsertTag
      responses:
        "200":
@@ -716,6 +726,7 @@ paths:
        - TagService
  /api/v2/tags/suggestion:
    get:
+      summary: GetTagSuggestions gets tag suggestions from the user's memos.
      operationId: TagService_GetTagSuggestions
      responses:
        "200":
@@ -738,6 +749,7 @@ paths:
        - TagService
  /api/v2/tags:batchUpsert:
    post:
+      summary: BatchUpsertTag upserts multiple tags.
      operationId: TagService_BatchUpsertTag
      responses:
        "200":
@@ -752,6 +764,9 @@ paths:
        - TagService
  /api/v2/tags:rename:
    patch:
+      summary: |-
+        RenameTag renames a tag.
+        All related memos will be updated.
      operationId: TagService_RenameTag
      responses:
        "200":
@@ -797,6 +812,7 @@ paths:
        - UserService
  /api/v2/webhooks:
    get:
+      summary: ListWebhooks returns a list of webhooks.
      operationId: WebhookService_ListWebhooks
      responses:
        "200":
@@ -816,6 +832,7 @@ paths:
      tags:
        - WebhookService
    post:
+      summary: CreateWebhook creates a new webhook.
      operationId: WebhookService_CreateWebhook
      responses:
        "200":
@@ -836,6 +853,7 @@ paths:
        - WebhookService
  /api/v2/webhooks/{id}:
    get:
+      summary: GetWebhook returns a webhook by id.
      operationId: WebhookService_GetWebhook
      responses:
        "200":
@@ -855,6 +873,7 @@ paths:
      tags:
        - WebhookService
    delete:
+      summary: DeleteWebhook deletes a webhook by id.
      operationId: WebhookService_DeleteWebhook
      responses:
        "200":
@@ -875,6 +894,7 @@ paths:
        - WebhookService
  /api/v2/webhooks/{webhook.id}:
    patch:
+      summary: UpdateWebhook updates a webhook.
      operationId: WebhookService_UpdateWebhook
      responses:
        "200":
@@ -900,6 +920,7 @@ paths:
        - WebhookService
  /api/v2/workspace/profile:
    get:
+      summary: GetWorkspaceProfile returns the workspace profile.
      operationId: WorkspaceService_GetWorkspaceProfile
      responses:
        "200":
@@ -913,6 +934,7 @@ paths:
      tags:
        - WorkspaceService
    patch:
+      summary: UpdateWorkspaceProfile updates the workspace profile.
      operationId: WorkspaceService_UpdateWorkspaceProfile
      responses:
        "200":
@@ -1062,6 +1084,7 @@ paths:
        - UserService
  /api/v2/{name}/setting:
    get:
+      summary: GetUserSetting gets the setting of a user.
      operationId: UserService_GetUserSetting
      responses:
        "200":
@@ -1085,6 +1108,7 @@ paths:
        - UserService
  /api/v2/{setting.name}:
    patch:
+      summary: UpdateUserSetting updates the setting of a user.
      operationId: UserService_UpdateUserSetting
      responses:
        "200":
@@ -1200,6 +1224,7 @@ paths:
        - UserService
  /v2/activities:
    get:
+      summary: GetActivity returns the activity with the given id.
      operationId: ActivityService_GetActivity
      responses:
        "200":
@@ -1220,6 +1245,7 @@ paths:
        - ActivityService
  /v2/inboxes:
    patch:
+      summary: UpdateInbox updates an inbox.
      operationId: InboxService_UpdateInbox
      responses:
        "200":
@@ -1240,6 +1266,7 @@ paths:
        - InboxService
  /v2/{name}:
    delete:
+      summary: DeleteInbox deletes an inbox.
      operationId: InboxService_DeleteInbox
      responses:
        "200":