node-cnb 1.5.0 → 1.6.0

package/src/client.d.ts

@@ -83,15 +83,47 @@ import {
 
 export interface Client {
   groups: {
+    /***
+     * 创建新组织
+     *
+     * 访问令牌调用此接口需包含以下权限
+     * group-manage:rw
+     *
+     * /groups
+     */
     post: (params: { request: DtoCreateGroupReq }) => Promise<any>;
   };
 
   user: {
+    /***
+     * 获取指定用户的详情信息
+     *
+     * 访问令牌调用此接口需包含以下权限
+     * account-profile:r
+     *
+     * /user
+     */
     get: (params: {}) => Promise<DtoUsersResultForSelf>;
 
+    /***
+     * 更新指定用户的详情信息, 可更新内容为: 昵称, 个人签名, 微信公众号名称, 微信公众号二维码链接, 个人网站, 个人地址, 公司名称
+     *
+     * 访问令牌调用此接口需包含以下权限
+     * account-profile:rw
+     *
+     * /user
+     */
     post: (params: { request: HttpUpdateUserInfoPayload }) => Promise<any>;
 
     autocompleteSource: {
+      /***
+       * 查询当前用户用户拥有指定权限的所有资源列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /user/autocomplete_source
+       */
       list: (params: {
         source_type?: "Group" | "Repo";
         page?: number;
@@ -102,6 +134,14 @@ export interface Client {
     };
 
     groups: {
+      /***
+       * 获取当前用户拥有权限的顶层组织列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /user/groups
+       */
       list: (params: {
         page?: number;
         page_size?: number;
@@ -109,6 +149,14 @@ export interface Client {
         role?: "Guest" | "Reporter" | "Developer" | "Master" | "Owner";
       }) => Promise<DtoOrganizationAccess[]>;
 
+      /***
+       * 查询当前用户在指定组织下拥有指定权限的子组织列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /user/groups/{group}
+       */
       listByGroup: (params: {
         group: string;
         page?: number;
@@ -118,6 +166,14 @@ export interface Client {
     };
 
     repos: {
+      /***
+       * 获取当前用户拥有指定权限及其以上权限的仓库
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /user/repos
+       */
       list: (params: {
         page?: number;
         page_size?: number;
@@ -130,6 +186,14 @@ export interface Client {
     };
 
     staredRepos: {
+      /***
+       * 获取当前用户 star 的仓库列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /user/stared-repos
+       */
       list: (params: {
         page?: number;
         page_size?: number;
@@ -141,13 +205,37 @@ export interface Client {
   };
 
   users: {
+    /***
+     * 获取指定用户的详情信息
+     *
+     * 访问令牌调用此接口需包含以下权限
+     * account-profile:r
+     *
+     * /users/{username}
+     */
     get: (params: { username: string }) => Promise<DtoUsersResult>;
 
     avatar: {
+      /***
+       * 获取指定用户的用户头像
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-profile:r
+       *
+       * /users/{username}/avatar/{size}
+       */
       get: (params: { username: string; size: string }) => Promise<any>;
     };
 
     followers: {
+      /***
+       * 获取指定用户的粉丝列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /users/{username}/followers
+       */
       list: (params: {
         username: string;
         page?: number;
@@ -156,6 +244,14 @@ export interface Client {
     };
 
     following: {
+      /***
+       * 获取指定用户的关注人列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /users/{username}/following
+       */
       list: (params: {
         username: string;
         page?: number;
@@ -164,6 +260,14 @@ export interface Client {
     };
 
     groups: {
+      /***
+       * 获取指定用户拥有权限的顶层组织列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /users/{username}/groups
+       */
       get: (params: {
         username: string;
         search?: string;
@@ -175,10 +279,26 @@ export interface Client {
     };
 
     pinnedRepos: {
+      /***
+       * 获取指定用户的用户仓库墙
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /users/{username}/pinned-repos
+       */
       list: (params: { username: string }) => Promise<DtoRepos4User[]>;
     };
 
     repos: {
+      /***
+       * 获取指定用户有指定以上权限并且客人态可见的仓库
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /users/{username}/repos
+       */
       list: (params: {
         username: string;
         search?: string;
@@ -191,6 +311,14 @@ export interface Client {
     };
 
     staredRepos: {
+      /***
+       * 获取指定用户的 star 仓库列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /users/{username}/stared-repos
+       */
       list: (params: {
         username: string;
         search?: string;
@@ -204,12 +332,28 @@ export interface Client {
 
   workspace: {
     delete: {
+      /***
+       * 删除我的云原生开发环境
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:rw
+       *
+       * /workspace/delete
+       */
       post: (params: {
         request: DtoWorkspaceDeleteReq;
       }) => Promise<DtoWorkspaceDeleteResult>;
     };
 
     list: {
+      /***
+       * 获取我的云原生开发环境列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * account-engage:r
+       *
+       * /workspace/list
+       */
       get: (params: {
         branch?: string;
         end?: string;
@@ -223,9 +367,25 @@ export interface Client {
   };
 
   group: {
+    /***
+     * 获取指定组织信息
+     *
+     * 访问令牌调用此接口需包含以下权限
+     * group-resource:r
+     *
+     * /{group}
+     */
     get: (params: { group: string }) => Promise<DtoOrganizationAccess>;
 
     avatar: {
+      /***
+       * 更新组织头像 URL 地址
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:rw
+       *
+       * /{group}/-/avatar
+       */
       put: (params: {
         group: string;
         request: DtoUpdateGroupAvatarReq;
@@ -233,6 +393,14 @@ export interface Client {
     };
 
     inheritMembers: {
+      /***
+       * 获取指定组织或仓库内的继承成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:r
+       *
+       * /{group}/-/inherit-members
+       */
       list: (params: {
         group: string;
         search?: string;
@@ -243,6 +411,14 @@ export interface Client {
     };
 
     listMembers: {
+      /***
+       * 获取指定组织或仓库内的有效成员列表，包含继承成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:r
+       *
+       * /{group}/-/list-members
+       */
       list: (params: {
         group: string;
         page?: number;
@@ -256,12 +432,36 @@ export interface Client {
     };
 
     logos: {
+      /***
+       * 确认上传的logo
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:rw
+       *
+       * /{group}/-/logos
+       */
       put: (params: { group: string; token: string }) => Promise<any>;
 
+      /***
+       * 发起一个获取 logo 的请求，返回内容或者 302 到某个地址
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-resource:r
+       *
+       * /{group}/-/logos/{size}
+       */
       get: (params: { group: string; size?: string }) => Promise<any>;
     };
 
     members: {
+      /***
+       * 获取指定组织或仓库内的所有直接成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:r
+       *
+       * /{group}/-/members
+       */
       list: (params: {
         group: string;
         page?: number;
@@ -271,19 +471,51 @@ export interface Client {
       }) => Promise<DtoUsersWithAccessLevelInSlug[]>;
 
       accessLevel: {
+        /***
+         * 获取指定组织或仓库内, 访问成员在当前层级内的权限信息
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * group-manage:r
+         *
+         * /{group}/-/members/access-level
+         */
         get: (params: {
           group: string;
           include_inherit?: boolean;
         }) => Promise<DtoMemberAccessLevelInSlugUnion>;
 
+        /***
+         * 获取指定组织或仓库内指定成员的权限信息, 结果按组织层级来展示, 包含上层组织的权限继承信息
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * group-manage:r
+         *
+         * /{group}/-/members/{username}/access-level
+         */
         list: (params: {
           group: string;
           username: string;
         }) => Promise<DtoMemberAccessLevel[]>;
       };
 
+      /***
+       * 删除指定组织或仓库的直接成员, 包含两种场景: 1. 作为直接成员的用户自己退出 2. 由管理者移除指定的直接成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:rw
+       *
+       * /{group}/-/members/{username}
+       */
       delete: (params: { group: string; username: string }) => Promise<any>;
 
+      /***
+       * 更新指定组织或仓库内的直接成员权限信息
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:rw
+       *
+       * /{group}/-/members/{username}
+       */
       put: (params: {
         group: string;
         username: string;
@@ -292,8 +524,24 @@ export interface Client {
     };
 
     pinnedRepos: {
+      /***
+       * 获取指定组织的仓库墙列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:r
+       *
+       * /{group}/-/pinned-repos
+       */
       list: (params: { group: string }) => Promise<DtoRepos4UserBase[]>;
 
+      /***
+       * 更新指定组织仓库墙
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:rw
+       *
+       * /{group}/-/pinned-repos
+       */
       put: (params: {
         group: string;
         request: string[];
@@ -301,6 +549,14 @@ export interface Client {
     };
 
     repos: {
+      /***
+       * 查询组织下访问用户有权限查看到仓库
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-resource:r
+       *
+       * /{group}/-/repos
+       */
       list: (params: {
         group: string;
         page?: number;
@@ -312,6 +568,14 @@ export interface Client {
         search?: string;
       }) => Promise<DtoRepos4UserBase[]>;
 
+      /***
+       * 创建仓库
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-resource:rw
+       *
+       * /{group}/-/repos
+       */
       post: (params: {
         group: string;
         request: DtoCreateRepoReq;
@@ -319,10 +583,26 @@ export interface Client {
     };
 
     settings: {
+      /***
+       * 获取指定组织的配置详情
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:r
+       *
+       * /{group}/-/settings
+       */
       get: (params: {
         group: string;
       }) => Promise<DtoOrganizationSettingWithParent>;
 
+      /***
+       * 更新指定组织的配置, 可更新内容为: 是否对外隐藏组织成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-manage:rw
+       *
+       * /{group}/-/settings
+       */
       put: (params: {
         group: string;
         request: DtoGroupSettingReq;
@@ -330,6 +610,14 @@ export interface Client {
     };
 
     subGroups: {
+      /***
+       * 获取指定组织下的子组织列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-resource:r
+       *
+       * /{group}/-/sub-groups
+       */
       list: (params: {
         group: string;
         search?: string;
@@ -340,6 +628,14 @@ export interface Client {
 
     upload: {
       logos: {
+        /***
+         * 发起一个上传 logo 的请求，返回上传 cos 的 url 和 form 内容
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * group-manage:rw
+         *
+         * /{group}/-/upload/logos
+         */
         post: (params: {
           group: string;
           request: DtoUploadRequestParams;
@@ -352,6 +648,14 @@ export interface Client {
     packages: {
       name: {
         tag: {
+          /***
+           * Delete the specific tag
+           *
+           * 访问令牌调用此接口需包含以下权限
+           * repo-registry-delete:rw
+           *
+           * /{registry}/-/packages/{type}/{name}/-/tag/{tag}
+           */
           delete: (params: {
             registry: string;
             type: "docker" | "helm";
@@ -364,10 +668,26 @@ export interface Client {
   };
 
   repo: {
+    /***
+     * 获取指定仓库信息
+     *
+     * 访问令牌调用此接口需包含以下权限
+     * repo-basic-info:r
+     *
+     * /{repo}
+     */
     get: (params: { repo: string }) => Promise<DtoRepos4User>;
 
     build: {
       logs: {
+        /***
+         * 查询流水线构建列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-cnb-trigger:r
+         *
+         * /{repo}/-/build/logs
+         */
         get: (params: {
           repo: string;
           createTime?: string;
@@ -386,6 +706,14 @@ export interface Client {
       };
 
       start: {
+        /***
+         * 开始一个构建
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-cnb-trigger:rw
+         *
+         * /{repo}/-/build/start
+         */
         post: (params: {
           repo: string;
           request: DtoStartBuildReq;
@@ -393,6 +721,14 @@ export interface Client {
       };
 
       status: {
+        /***
+         * 查询流水线构建状态
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-cnb-trigger:r
+         *
+         * /{repo}/-/build/status/{sn}
+         */
         get: (params: {
           repo: string;
           sn: string;
@@ -400,6 +736,14 @@ export interface Client {
       };
 
       stop: {
+        /***
+         * 停止一个构建
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-cnb-trigger:rw
+         *
+         * /{repo}/-/build/stop/{sn}
+         */
         post: (params: {
           repo: string;
           sn: string;
@@ -409,11 +753,27 @@ export interface Client {
 
     commitAssets: {
       download: {
+        /***
+         * 发起一个获取 commits 附件的请求，返回内容或者 302 到某个地址
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-contents:r
+         *
+         * /{repo}/-/commit-assets/download/{fileName}
+         */
         get: (params: { repo: string; fileName: string }) => Promise<any>;
       };
     };
 
     files: {
+      /***
+       * 发起一个获取 files 的请求，返回内容或者 302 到某个地址
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-contents:r
+       *
+       * /{repo}/-/files/{userIdKey}/{randomUUID}/{fileName}
+       */
       get: (params: {
         repo: string;
         userIdKey: string;
@@ -421,6 +781,14 @@ export interface Client {
         fileName: string;
       }) => Promise<any>;
 
+      /***
+       * 发起一个确认 files 的请求，上传的图片要调用此接口才能生效
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-contents:rw
+       *
+       * /{repo}/-/files/{userIdKey}/{randomUUID}/{fileName}
+       */
       put: (params: {
         repo: string;
         userIdKey: string;
@@ -431,30 +799,78 @@ export interface Client {
     };
 
     forks: {
+      /***
+       * 获取指定仓库的 fork 列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-base-info:r
+       *
+       * /{repo}/-/forks
+       */
       list: (params: {
         repo: string;
         page: number;
         page_size: number;
       }) => Promise<DtoForks[]>;
 
+      /***
+       * fork 仓库
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * group-resource:rw
+       *
+       * /{repo}/-/forks
+       */
       post: (params: { repo: string; request: DtoForkReq }) => Promise<any>;
     };
 
     git: {
       branches: {
+        /***
+         * 查询分支列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/branches
+         */
         list: (params: {
           repo: string;
           page?: number;
           page_size?: number;
         }) => Promise<ApiBranch[]>;
 
+        /***
+         * 创建新分支
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/branches
+         */
         post: (params: {
           repo: string;
           create_branch_form: OpenapiCreateBranchForm;
         }) => Promise<any>;
 
+        /***
+         * 删除指定分支
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/branches/{branch}
+         */
         delete: (params: { repo: string; branch: string }) => Promise<any>;
 
+        /***
+         * 查询指定分支
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/branches/{branch}
+         */
         get: (params: {
           repo: string;
           branch?: string;
@@ -462,6 +878,14 @@ export interface Client {
       };
 
       commitAnnotationsInBatch: {
+        /***
+         * 查询指定 commit 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/commit-annotations-in-batch
+         */
         post: (params: {
           repo: string;
           get_commit_annotations_form: WebGetCommitAnnotationsInBatchForm;
@@ -469,17 +893,41 @@ export interface Client {
       };
 
       commitAnnotations: {
+        /***
+         * 查询指定 commit 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/commit-annotations/{sha}
+         */
         list: (params: {
           repo: string;
           sha: string;
         }) => Promise<WebCommitAnnotation[]>;
 
+        /***
+         * 设定指定 commit 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/commit-annotations/{sha}
+         */
         put: (params: {
           repo: string;
           sha: string;
           put_commit_annotations_form: OpenapiPutCommitAnnotationsForm;
         }) => Promise<any>;
 
+        /***
+         * 删除指定 commit 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/commit-annotations/{sha}/{key}
+         */
         delete: (params: {
           repo: string;
           sha: string;
@@ -488,12 +936,28 @@ export interface Client {
       };
 
       commitAssets: {
+        /***
+         * 查询指定 commit 的附件
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/commit-assets/{sha1}
+         */
         list: (params: {
           repo: string;
           sha1: string;
         }) => Promise<ApiCommitAsset[]>;
 
         assetUploadConfirmation: {
+          /***
+           * 确认 Commit asset 上传完成
+           *
+           * 访问令牌调用此接口需包含以下权限
+           * repo-code:rw
+           *
+           * /{repo}/-/git/commit-assets/{sha1}/asset-upload-confirmation/{token}/{asset_path}
+           */
           post: (params: {
             repo: string;
             sha1: number;
@@ -503,6 +967,14 @@ export interface Client {
         };
 
         assetUploadUrl: {
+          /***
+           * 新增一个 Commit asset
+           *
+           * 访问令牌调用此接口需包含以下权限
+           * repo-code:rw
+           *
+           * /{repo}/-/git/commit-assets/{sha1}/asset-upload-url
+           */
           post: (params: {
             repo: string;
             sha1: number;
@@ -510,6 +982,14 @@ export interface Client {
           }) => Promise<any>;
         };
 
+        /***
+         * 删除指定 commit 的附件
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/commit-assets/{sha1}/{asset_id}
+         */
         delete: (params: {
           repo: string;
           sha1: string;
@@ -518,6 +998,14 @@ export interface Client {
       };
 
       commitStatuses: {
+        /***
+         * 查询指定 commit 的 check statuses
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/commit-statuses/{commitish}
+         */
         list: (params: {
           repo: string;
           sha: string;
@@ -525,6 +1013,14 @@ export interface Client {
       };
 
       commits: {
+        /***
+         * 查询 commit 列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/commits
+         */
         list: (params: {
           repo: string;
           sha?: string;
@@ -536,10 +1032,26 @@ export interface Client {
           page_size?: number;
         }) => Promise<ApiCommit[]>;
 
+        /***
+         * 查询指定 commit
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/commits/{ref}
+         */
         get: (params: { repo: string; ref: string }) => Promise<ApiCommit>;
       };
 
       compare: {
+        /***
+         * 对比 base...head
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/compare/{base_head}
+         */
         get: (params: {
           repo: string;
           base_head: string;
@@ -547,6 +1059,14 @@ export interface Client {
       };
 
       contents: {
+        /***
+         * 查询仓库文件列表或文件
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/contents/{file_path}
+         */
         get: (params: {
           repo: string;
           file_path: string;
@@ -555,20 +1075,52 @@ export interface Client {
       };
 
       head: {
+        /***
+         * 获取仓库默认分支
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/head
+         */
         get: (params: { repo: string }) => Promise<OpenapiHeadRef>;
       };
 
       tagAnnotations: {
+        /***
+         * 删除指定 tag 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/tag-annotations/{tag_with_key}
+         */
         delete: (params: {
           repo: string;
           tag_with_key: string;
         }) => Promise<any>;
 
+        /***
+         * 查询指定 tag 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/tag-annotations/{tag}
+         */
         list: (params: {
           repo: string;
           tag: string;
         }) => Promise<WebTagAnnotation[]>;
 
+        /***
+         * 设定指定 tag 的元数据
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/tag-annotations/{tag}
+         */
         put: (params: {
           repo: string;
           tag: string;
@@ -577,25 +1129,65 @@ export interface Client {
       };
 
       tags: {
+        /***
+         * 查询标签列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/tags
+         */
         list: (params: {
           repo: string;
           page?: number;
           page_size?: number;
         }) => Promise<ApiTag[]>;
 
+        /***
+         * 删除指定标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/git/tags/{tag}
+         */
         delete: (params: { repo: string; tag: string }) => Promise<any>;
 
+        /***
+         * 查询指定 Tag
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/git/tags/{tag}
+         */
         get: (params: { repo: string; tag: string }) => Promise<ApiTag>;
       };
     };
 
     imgs: {
+      /***
+       * 发起一个获取 imgs 的请求，返回内容或者 302 到某个地址
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-contents:r
+       *
+       * /{repo}/-/imgs/{userIdKey}/{fileName}
+       */
       get: (params: {
         repo: string;
         userIdKey: string;
         fileName: string;
       }) => Promise<any>;
 
+      /***
+       * 发起一个确认 imgs 的请求，上传的图片要调用此接口才能生效
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-contents:rw
+       *
+       * /{repo}/-/imgs/{userIdKey}/{fileName}
+       */
       put: (params: {
         repo: string;
         userIdKey: string;
@@ -605,6 +1197,14 @@ export interface Client {
     };
 
     inheritMembers: {
+      /***
+       * 获取指定组织或仓库内的继承成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:r
+       *
+       * /{repo}/-/inherit-members
+       */
       list: (params: {
         repo: string;
         search?: string;
@@ -615,6 +1215,14 @@ export interface Client {
     };
 
     issues: {
+      /***
+       * 查询仓库的 Issues
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:r
+       *
+       * /{repo}/-/issues
+       */
       list: (params: {
         repo: string;
         page?: number;
@@ -630,11 +1238,27 @@ export interface Client {
         order_by?: string;
       }) => Promise<ApiIssue[]>;
 
+      /***
+       * 创建一个 Issue
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:rw
+       *
+       * /{repo}/-/issues
+       */
       post: (params: {
         repo: string;
         post_issue_form: ApiPostIssueForm;
       }) => Promise<any>;
 
+      /***
+       * 更新一个 Issue
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:rw
+       *
+       * /{repo}/-/issues/{number}
+       */
       patch: (params: {
         repo: string;
         number: number;
@@ -642,6 +1266,14 @@ export interface Client {
       }) => Promise<ApiIssueDetail>;
 
       comments: {
+        /***
+         * 查询仓库的 Issue 评论列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:r
+         *
+         * /{repo}/-/issues/{number}/comments
+         */
         list: (params: {
           repo: string;
           number: number;
@@ -649,18 +1281,42 @@ export interface Client {
           page_size?: number;
         }) => Promise<ApiIssueComment[]>;
 
+        /***
+         * 创建一个 Issue Comment
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/issues/{number}/comments
+         */
         post: (params: {
           repo: string;
           number: number;
           post_issue_comment_form: ApiPostIssueCommentForm;
         }) => Promise<any>;
 
+        /***
+         * 获取一个 Issue Comment
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:r
+         *
+         * /{repo}/-/issues/{number}/comments/{comment_id}
+         */
         get: (params: {
           repo: string;
           number: number;
           comment_id: number;
         }) => Promise<ApiIssueComment>;
 
+        /***
+         * 修改一个 Issue Comment
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/issues/{number}/comments/{comment_id}
+         */
         patch: (params: {
           repo: string;
           number: number;
@@ -670,8 +1326,24 @@ export interface Client {
       };
 
       labels: {
+        /***
+         * 清空 Issue 标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/issues/{number}/labels
+         */
         delete: (params: { repo: string; number: number }) => Promise<any>;
 
+        /***
+         * 删除 Issue 标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/issues/{number}/labels/{name}
+         */
         deleteByName: (params: {
           repo: string;
           number: number;
@@ -681,6 +1353,14 @@ export interface Client {
     };
 
     labels: {
+      /***
+       * 查询仓库的标签(label) 列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:r
+       *
+       * /{repo}/-/labels
+       */
       list: (params: {
         repo: string;
         page?: number;
@@ -688,13 +1368,37 @@ export interface Client {
         keyword?: string;
       }) => Promise<ApiLabel[]>;
 
+      /***
+       * 创建一个 标签
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:rw
+       *
+       * /{repo}/-/labels
+       */
       post: (params: {
         repo: string;
         post_label_form: ApiPostLabelForm;
       }) => Promise<any>;
 
+      /***
+       * 删除指定的仓库标签 label
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:rw
+       *
+       * /{repo}/-/labels/{name}
+       */
       delete: (params: { repo: string; name: string }) => Promise<any>;
 
+      /***
+       * 更新标签信息
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-notes:rw
+       *
+       * /{repo}/-/labels/{name}
+       */
       patch: (params: {
         repo: string;
         name: string;
@@ -703,6 +1407,14 @@ export interface Client {
     };
 
     listMembers: {
+      /***
+       * 获取指定组织或仓库内的有效成员列表，包含继承成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:r
+       *
+       * /{repo}/-/list-members
+       */
       list: (params: {
         repo: string;
         page?: number;
@@ -716,6 +1428,14 @@ export interface Client {
     };
 
     members: {
+      /***
+       * 获取指定组织或仓库内的所有直接成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:r
+       *
+       * /{repo}/-/members
+       */
       list: (params: {
         repo: string;
         page?: number;
@@ -725,19 +1445,51 @@ export interface Client {
       }) => Promise<DtoUsersWithAccessLevelInSlug[]>;
 
       accessLevel: {
+        /***
+         * 获取指定组织或仓库内, 访问成员在当前层级内的权限信息
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/members/access-level
+         */
         get: (params: {
           repo: string;
           include_inherit?: boolean;
         }) => Promise<DtoMemberAccessLevelInSlugUnion>;
 
+        /***
+         * 获取指定组织或仓库内指定成员的权限信息, 结果按组织层级来展示, 包含上层组织的权限继承信息
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/members/{username}/access-level
+         */
         list: (params: {
           repo: string;
           username: string;
         }) => Promise<DtoMemberAccessLevel[]>;
       };
 
+      /***
+       * 删除指定组织或仓库的直接成员, 包含两种场景: 1. 作为直接成员的用户自己退出 2. 由管理者移除指定的直接成员
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:rw
+       *
+       * /{repo}/-/members/{username}
+       */
       delete: (params: { repo: string; username: string }) => Promise<any>;
 
+      /***
+       * 更新指定组织或仓库内的直接成员权限信息
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:rw
+       *
+       * /{repo}/-/members/{username}
+       */
       put: (params: {
         repo: string;
         username: string;
@@ -746,6 +1498,14 @@ export interface Client {
     };
 
     outsideCollaborators: {
+      /***
+       * 获取指定仓库内的外部贡献者
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:r
+       *
+       * /{repo}/-/outside-collaborators
+       */
       list: (params: {
         repo: string;
         page?: number;
@@ -754,8 +1514,24 @@ export interface Client {
         search?: string;
       }) => Promise<DtoOutsideCollaboratorInRepo[]>;
 
+      /***
+       * 删除指定仓库的外部贡献者, 包含两种场景: 1. 作为外部贡献者的用户自己退出仓库 2. 由仓库管理者移除指定的外部贡献者
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:rw
+       *
+       * /{repo}/-/outside-collaborators/{username}
+       */
       delete: (params: { repo: string; username: string }) => Promise<any>;
 
+      /***
+       * 更新指定仓库的外部贡献者权限信息
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-manage:rw
+       *
+       * /{repo}/-/outside-collaborators/{username}
+       */
       put: (params: {
         repo: string;
         username: string;
@@ -764,6 +1540,14 @@ export interface Client {
     };
 
     pulls: {
+      /***
+       * [openapi] 查询 Pull 列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-pr:r
+       *
+       * /{repo}/-/pulls
+       */
       list: (params: {
         repo: string;
         page?: number;
@@ -774,13 +1558,37 @@ export interface Client {
         assignees?: string;
       }) => Promise<ApiPullRequest[]>;
 
+      /***
+       * [openapi] 新增一个 Pull
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-pr:rw
+       *
+       * /{repo}/-/pulls
+       */
       post: (params: {
         repo: string;
         post_pull_form: ApiPullCreationForm;
       }) => Promise<any>;
 
+      /***
+       * [openapi] 查询指定 Pull
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-pr:r
+       *
+       * /{repo}/-/pulls/{number}
+       */
       get: (params: { repo: string; number: number }) => Promise<ApiPull>;
 
+      /***
+       * [openapi] 更新一个 Pull Request
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-pr:rw
+       *
+       * /{repo}/-/pulls/{number}
+       */
       patch: (params: {
         repo: string;
         number: number;
@@ -788,12 +1596,28 @@ export interface Client {
       }) => Promise<ApiPull>;
 
       comments: {
+        /***
+         * [openapi] 查询 Pull Comments 列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:r
+         *
+         * /{repo}/-/pulls/{number}/comments
+         */
         list: (params: {
           repo: string;
           page?: number;
           page_size?: number;
         }) => Promise<ApiPullRequestComment[]>;
 
+        /***
+         * [openapi] 新增一个 Pull Comment
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/pulls/{number}/comments
+         */
         post: (params: {
           repo: string;
           number: number;
@@ -802,8 +1626,24 @@ export interface Client {
       };
 
       labels: {
+        /***
+         * 清空 Pull 标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/pulls/{number}/labels
+         */
         delete: (params: { repo: string; number: number }) => Promise<any>;
 
+        /***
+         * 查询 Pull 的标签(label) 列表
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:r
+         *
+         * /{repo}/-/pulls/{number}/labels
+         */
         list: (params: {
           repo: string;
           number: number;
@@ -811,18 +1651,42 @@ export interface Client {
           page_size?: number;
         }) => Promise<ApiLabel[]>;
 
+        /***
+         * 新增 Pull 标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/pulls/{number}/labels
+         */
         post: (params: {
           repo: string;
           number: number;
           post_pull_labels_form: ApiPostPullLabelsForm;
         }) => Promise<ApiLabel>;
 
+        /***
+         * 设置 Pull 标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/pulls/{number}/labels
+         */
         put: (params: {
           repo: string;
           number: number;
           put_pull_labels_form: ApiPutPullLabelsForm;
         }) => Promise<ApiLabel>;
 
+        /***
+         * 删除 Pull 标签
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/pulls/{number}/labels/{name}
+         */
         deleteByName: (params: {
           repo: string;
           number: number;
@@ -831,6 +1695,14 @@ export interface Client {
       };
 
       merge: {
+        /***
+         * [openapi] 合并一个 Pull Request
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-pr:rw
+         *
+         * /{repo}/-/pulls/{number}/merge
+         */
         put: (params: {
           repo: string;
           number: number;
@@ -839,6 +1711,14 @@ export interface Client {
       };
 
       reviews: {
+        /***
+         * [openapi] 新增一个 Pull Review
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-notes:rw
+         *
+         * /{repo}/-/pulls/{number}/reviews
+         */
         post: (params: {
           repo: string;
           number: number;
@@ -848,32 +1728,88 @@ export interface Client {
     };
 
     releases: {
+      /***
+       * [openapi] 查询 release 列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-code:r
+       *
+       * /{repo}/-/releases
+       */
       list: (params: {
         repo: string;
         page?: number;
         page_size?: number;
       }) => Promise<ApiRelease[]>;
 
+      /***
+       * [openapi] 新增一个 Release
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-code:rw
+       *
+       * /{repo}/-/releases
+       */
       post: (params: {
         repo: string;
         create_release_form: OpenapiPostReleaseForm;
       }) => Promise<any>;
 
       download: {
+        /***
+         * 发起一个获取 release 附件的请求，返回内容或者 302 到某个地址
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-contents:r
+         *
+         * /{repo}/-/releases/download/{fileName}
+         */
         get: (params: { repo: string; fileName: string }) => Promise<any>;
       };
 
       tags: {
+        /***
+         * [openapi] 通过 tag 查询指定 release
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/releases/tags/{tag}
+         */
         get: (params: { repo: string; tag: string }) => Promise<ApiRelease>;
       };
 
+      /***
+       * [openapi] 删除指定的 release
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-code:rw
+       *
+       * /{repo}/-/releases/{release_id}
+       */
       delete: (params: { repo: string; release_id: number }) => Promise<any>;
 
+      /***
+       * [openapi] 根据 id	查询指定 release
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-code:r
+       *
+       * /{repo}/-/releases/{release_id}
+       */
       get: (params: {
         repo: string;
         release_id: number;
       }) => Promise<ApiRelease>;
 
+      /***
+       * [openapi] 更新 release
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-code:rw
+       *
+       * /{repo}/-/releases/{release_id}
+       */
       patch: (params: {
         repo: string;
         release_id: number;
@@ -881,6 +1817,14 @@ export interface Client {
       }) => Promise<any>;
 
       assetUploadConfirmation: {
+        /***
+         * [openapi] 确认 Release asset 上传完成
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/releases/{release_id}/asset-upload-confirmation/{token}/{asset_path}
+         */
         post: (params: {
           repo: string;
           release_id: number;
@@ -890,6 +1834,14 @@ export interface Client {
       };
 
       assetUploadUrl: {
+        /***
+         * [openapi] 新增一个 Release asset
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/releases/{release_id}/asset-upload-url
+         */
         post: (params: {
           repo: string;
           release_id: number;
@@ -898,12 +1850,28 @@ export interface Client {
       };
 
       assets: {
+        /***
+         * [openapi] 删除指定的 release asset
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:rw
+         *
+         * /{repo}/-/releases/{release_id}/assets/{asset_id}
+         */
         delete: (params: {
           repo: string;
           release_id: number;
           asset_id: number;
         }) => Promise<any>;
 
+        /***
+         * [openapi] 查询指定的 release asset
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-code:r
+         *
+         * /{repo}/-/releases/{release_id}/assets/{asset_id}
+         */
         get: (params: {
           repo: string;
           release_id: number;
@@ -914,20 +1882,60 @@ export interface Client {
 
     settings: {
       branchProtections: {
+        /***
+         * 查询仓库保护分支规则列表(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/settings/branch-protections
+         */
         list: (params: { repo: string }) => Promise<ApiBranchProtection[]>;
 
+        /***
+         * 新增仓库保护分支规则(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:rw
+         *
+         * /{repo}/-/settings/branch-protections
+         */
         post: (params: {
           repo: string;
           branch_protection_form: ApiBranchProtection;
         }) => Promise<any>;
 
+        /***
+         * 删除仓库保护分支规则(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:rw
+         *
+         * /{repo}/-/settings/branch-protections/{id}
+         */
         delete: (params: { repo: string; id: string }) => Promise<any>;
 
+        /***
+         * 查询仓库保护分支规则(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/settings/branch-protections/{id}
+         */
         get: (params: {
           repo: string;
           id: string;
         }) => Promise<ApiBranchProtection>;
 
+        /***
+         * 更新仓库保护分支规则(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:rw
+         *
+         * /{repo}/-/settings/branch-protections/{id}
+         */
         patch: (params: {
           repo: string;
           id: string;
@@ -936,8 +1944,24 @@ export interface Client {
       };
 
       cloudNativeBuild: {
+        /***
+         * 查询仓库云原生构建设置(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/settings/cloud-native-build
+         */
         get: (params: { repo: string }) => Promise<ApiPipelineSettings>;
 
+        /***
+         * 更新仓库云原生构建设置(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:rw
+         *
+         * /{repo}/-/settings/cloud-native-build
+         */
         put: (params: {
           repo: string;
           pipeline_form: WebPipelineSettings;
@@ -945,8 +1969,24 @@ export interface Client {
       };
 
       pullRequest: {
+        /***
+         * 查询仓库合并请求设置(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/settings/pull-request
+         */
         get: (params: { repo: string }) => Promise<ApiPullRequestSettings>;
 
+        /***
+         * 设置仓库推送设置(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:rw
+         *
+         * /{repo}/-/settings/pull-request
+         */
         put: (params: {
           repo: string;
           pull_request_form: ApiPullRequestSettings;
@@ -954,8 +1994,24 @@ export interface Client {
       };
 
       pushLimit: {
+        /***
+         * 查询仓库推送设置(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:r
+         *
+         * /{repo}/-/settings/push-limit
+         */
         get: (params: { repo: string }) => Promise<ApiPushLimitSettings>;
 
+        /***
+         * 设置仓库推送设置(openapi)
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-manage:rw
+         *
+         * /{repo}/-/settings/push-limit
+         */
         put: (params: {
           repo: string;
           push_limit_form: ApiPushLimitSettings;
@@ -964,6 +2020,14 @@ export interface Client {
     };
 
     stars: {
+      /***
+       * 获取指定仓库的star用户列表
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-basic-info:r
+       *
+       * /{repo}/-/stars
+       */
       get: (params: {
         repo: string;
         filter_type: "all" | "followed";
@@ -973,6 +2037,14 @@ export interface Client {
     };
 
     topActivityUsers: {
+      /***
+       * 获取 top 贡献用户
+       *
+       * 访问令牌调用此接口需包含以下权限
+       * repo-base-info:r
+       *
+       * /{repo}/-/top-activity-users
+       */
       list: (params: {
         repo: string;
         top?: number;
@@ -981,6 +2053,14 @@ export interface Client {
 
     upload: {
       files: {
+        /***
+         * 发起一个上传 files（issue，pr 及其评论中文档，压缩包等）的请求，返回上传 cos 的 url 和 form 内容
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-contents:rw
+         *
+         * /{repo}/-/upload/files
+         */
         post: (params: {
           repo: string;
           request: DtoUploadRequestParams;
@@ -988,6 +2068,14 @@ export interface Client {
       };
 
       imgs: {
+        /***
+         * 发起一个上传 imgs 的请求，返回上传 cos 的 url 和 form 内容
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-contents:rw
+         *
+         * /{repo}/-/upload/imgs
+         */
         post: (params: {
           repo: string;
           request: DtoUploadRequestParams;
@@ -995,6 +2083,14 @@ export interface Client {
       };
 
       releases: {
+        /***
+         * 发起一个上传 release 附件的请求，返回上传 cos 的 url 和 form 内容
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-contents:rw
+         *
+         * /{repo}/-/upload/releases/{tagName}
+         */
         post: (params: {
           repo: string;
           tagName: string;
@@ -1005,6 +2101,14 @@ export interface Client {
 
     workspace: {
       detail: {
+        /***
+         * 根据流水线sn查询云原生开发访问地址
+         *
+         * 访问令牌调用此接口需包含以下权限
+         * repo-cnb-detail:r
+         *
+         * /{repo}/-/workspace/detail/{sn}
+         */
         get: (params: {
           repo: string;
           sn: string;