增加API注释

2025-11-03 12:20:27 +08:00 · 2023-06-17 21:05:03 +08:00
parent 6a7af9e5cd
commit 7d54f3e165
10 changed files with 116 additions and 25 deletions
--- a/build/rpc.json
+++ b/build/rpc.json
@@ -15293,7 +15293,7 @@
    },
    {
      "name": "CreateOriginResponse",
-      "code": "message CreateOriginResponse {\n\tint64 originId = 1;\n}",
+      "code": "message CreateOriginResponse {\n\tint64 originId = 1; // 创建的源站ID\n}",
      "doc": ""
    },
    {
@@ -15328,7 +15328,7 @@
    },
    {
      "name": "CreateReverseProxyRequest",
-      "code": "message CreateReverseProxyRequest {\n\tbytes schedulingJSON = 1;\n\tbytes primaryOriginsJSON = 2;\n\tbytes backupOriginsJSON = 3;\n}",
+      "code": "message CreateReverseProxyRequest {\n\tbytes schedulingJSON = 1; // 可选项，调度设置 @link json:scheduling\n\tbytes primaryOriginsJSON = 2; // 可选项，主要源站 @link json:origin_refs\n\tbytes backupOriginsJSON = 3; // 可选项，备用源站 @link json:origin_refs\n}",
      "doc": "创建反向代理"
    },
    {
@@ -15388,7 +15388,7 @@
    },
    {
      "name": "CreateServerRequest",
-      "code": "message CreateServerRequest {\n\tint64 userId = 1; // 可选参数，用户ID，如果不想指定用户，此值可以为0\n\tint64 adminId = 2; // 可选参数，管理员ID\n\tstring type = 3; // 类型：httpProxy（HTTP反向代理，一般CDN服务都选这个）、httpWeb（静态文件服务，只会从服务器上读取文件内容，不会转发到源站）、tcpProxy（TCP反向代理）、udpProxy（UDP反向代理）\n\tstring name = 4; // 网站名称，通常可以是一个域名\n\tstring description = 5; // 可选参数，网站描述\n\n\t// 配置相关\n\tbytes serverNamesJSON = 8; // 域名列表 @link json:server_names\n\tbytes serverNamesJON = 19 [deprecated = true]; // 已过期，请使用 serverNamesJSON 代替\n\tbytes httpJSON = 9; // HTTP协议，当type为httpProxy或者httpWeb时填写 @link json:http_protocol\n\tbytes httpsJSON = 10;  // HTTPS协议，当type为httpProxy或者httpWeb时填写 @link json:https_protocol\n\tbytes tcpJSON = 11;  // TCP协议，当type为tcpProxy时填写 @link json:tcp_protocol\n\tbytes tlsJSON = 12;  // TLS协议，当type为tcpProxy时填写 @link json:tls_protocol\n\tbytes unixJSON = 13; // 备用参数，不用填写\n\tbytes udpJSON = 14; // UDP协议，当type为udpProxy时填写 @link json:udp_protocol\n\tint64 webId = 15; // 可选参数，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作\n\tbytes reverseProxyJSON = 16; // 反向代理（包含源站）设置\n\trepeated int64 serverGroupIds = 17; // 所属网站分组ID列表\n\tint64 userPlanId = 18; // 可选参数，套餐ID\n\n\tint64 nodeClusterId = 30; // 所部署的集群ID\n\tbytes includeNodesJSON = 31; // 备用参数，不用填写\n\tbytes excludeNodesJSON = 32; // 备用参数，不用填写\n}",
+      "code": "message CreateServerRequest {\n\tint64 userId = 1; // 可选项，用户ID，如果不想指定用户，此值可以为0\n\tint64 adminId = 2; // 可选项，管理员ID\n\tstring type = 3; // 类型：httpProxy（HTTP反向代理，一般CDN服务都选这个）、httpWeb（静态文件服务，只会从服务器上读取文件内容，不会转发到源站）、tcpProxy（TCP反向代理）、udpProxy（UDP反向代理）\n\tstring name = 4; // 网站名称，通常可以是一个域名\n\tstring description = 5; // 可选项，网站描述\n\n\t// 配置相关\n\tbytes serverNamesJSON = 8; // 域名列表 @link json:server_names\n\tbytes serverNamesJON = 19 [deprecated = true]; // 已过期，请使用 serverNamesJSON 代替\n\tbytes httpJSON = 9; // HTTP协议，当type为httpProxy或者httpWeb时填写 @link json:http_protocol\n\tbytes httpsJSON = 10;  // HTTPS协议，当type为httpProxy或者httpWeb时填写 @link json:https_protocol\n\tbytes tcpJSON = 11;  // TCP协议，当type为tcpProxy时填写 @link json:tcp_protocol\n\tbytes tlsJSON = 12;  // TLS协议，当type为tcpProxy时填写 @link json:tls_protocol\n\tbytes unixJSON = 13; // 备用参数，不用填写\n\tbytes udpJSON = 14; // UDP协议，当type为udpProxy时填写 @link json:udp_protocol\n\tint64 webId = 15; // 可选项，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作\n\tbytes reverseProxyJSON = 16; // 反向代理（包含源站）配置引用，此项可以在创建网站后再设置 @link json:reverse_proxy_ref\n\trepeated int64 serverGroupIds = 17; // 可选项，所属网站分组ID列表\n\tint64 userPlanId = 18; // 可选项，套餐ID\n\n\tint64 nodeClusterId = 30; // 所部署的集群ID\n\tbytes includeNodesJSON = 31; // 备用参数，不用填写\n\tbytes excludeNodesJSON = 32; // 备用参数，不用填写\n}",
      "doc": "创建网站"
    },
    {
@@ -22863,6 +22863,18 @@
      "name": "json:https_protocol",
      "content": "# HTTPS协议配置\n\n## 定义\n~~~json\n{\n\t\"isOn\": \"是否启用\",\n  \t\"listen\": [\n      {\n\t\t\"protocol\": \"协议\",\n\t\t\"host\": \"主机地址，通常为空\",\n\t\t\"portRange\": \"端口或者端口范围\"\n\t  },\n\t  ...\n\t],\n  \t\"sslPolicyRef\": {\n\t  \"isOn\": \"启用SSL策略\",\n\t  \"sslPolicyId\": \"SSL策略ID\"\n\t}\n}\n~~~\n\n其中 `SSL策略ID` 通过 `/SSLPolicyService/createSSLPolicy` 接口创建。\n\n## 示例\n\n### 监听443端口\n~~~json\n{\n  \"isOn\": true,\n  \"listen\": [\n    {\n      \"protocol\": \"https\",\n      \"host\": \"\",\n      \"portRange\": \"443\"\n\t}\n  ],\n  \"sslPolicyRef\": {\n    \"isOn\": true,\n    \"sslPolicyId\": 123\n  }\n}\n~~~\n\n其中SSL策略ID `123` 通过 `/SSLPolicyService/createSSLPolicy` 接口创建。\n\n### 监听443和8443端口\n~~~json\n{\n  \"isOn\": true,\n  \"listen\": [\n    {\n      \"protocol\": \"https\",\n      \"portRange\": \"443\"\n\t},\n    {\n      \"protocol\": \"https\",\n      \"portRange\": \"8443\"\n\t}\n  ],\n  \"sslPolicyRef\": {\n    \"isOn\": true,\n    \"sslPolicyId\": 123\n  }\n}\n~~~\n\n其中SSL策略ID `123` 通过 `/SSLPolicyService/createSSLPolicy` 接口创建。"
    },
+    {
+      "name": "json:origin_refs",
+      "content": "# 源站引用列表\n\n## 定义\n~~~json\n[\n  {\n\t\"isOn\": \"是否启用\",\n\t\"originId\": \"源站ID 1\"\n  },\n  {\n    \"isOn\": \"是否启用\",\n    \"originId\": \"源站ID 2\"\n  },\n  ...\n]\n~~~\n\n其中：\n* `originId` - 源站ID，可以通过 `/OriginService/createOrigin` 接口创建源站后获得\n\n## 示例\n~~~json\n[\n  {\n\t\"isOn\": true,\n\t\"originId\": 1\n  },\n  {\n    \"isOn\": true,\n    \"originId\": 2,\n  }\n]\n~~~"
+    },
+    {
+      "name": "json:reverse_proxy_ref",
+      "content": "# 反向代理引用\n## 定义\n~~~json\n{\n  \"isOn\": \"是否启用\",\n  \"isPrior\": \"是否覆盖上级配置，用于路由规则\",\n  \"reverseProxyId\": \"反向代理ID\"\n}\n~~~\n其中：\n* `reverseProxyId` - 反向代理ID，可以通过 `/ReverseProxyService/createReverseProxy` 创建\n\n## 示例\n~~~json\n{\n  \"isOn\": true,\n  \"reverseProxyId\": 123\n}\n~~~"
+    },
+    {
+      "name": "json:scheduling",
+      "content": "# 反向代理调度\n## 定义\n~~~json\n{\n\t\"code\": \"调度方法代号\",\n    \"options\": \"调度选项\"\n}\n~~~\n\n其中：\n* `code` 调度方法代号\n  * `random` - 随机\n  * `roundRobin` - 轮询\n  * `hash` - Hash算法\n    * `key` - 自定义Key，可以使用请求变量，比如 `${remoteAddr}`\n  * `sticky` - Sticky算法\n    * `type` - 类型：cookie、header、argument\n    * `param` - 参数值\n\n\n## 示例\n~~~json\n{\n  \"code\": \"random\",\n  \"options\": null\n}\n~~~"
+    },
    {
      "name": "json:server_name",
      "content": "# 域名信息\n\n## 示例\n~~~json\n{\n  \"name\": \"example.com\",\n  \"type\": \"full\"\n}\n~~~"
--- a/pkg/rpc/jsons/origin_refs.md
+++ b/pkg/rpc/jsons/origin_refs.md
@@ -0,0 +1,33 @@
+# 源站引用列表
+
+## 定义
+~~~json
+[
+  {
+	"isOn": "是否启用",
+	"originId": "源站ID 1"
+  },
+  {
+    "isOn": "是否启用",
+    "originId": "源站ID 2"
+  },
+  ...
+]
+~~~
+
+其中：
+* `originId` - 源站ID，可以通过 `/OriginService/createOrigin` 接口创建源站后获得
+
+## 示例
+~~~json
+[
+  {
+	"isOn": true,
+	"originId": 1
+  },
+  {
+    "isOn": true,
+    "originId": 2,
+  }
+]
+~~~
--- a/pkg/rpc/jsons/reverse_proxy_ref.md
+++ b/pkg/rpc/jsons/reverse_proxy_ref.md
@@ -0,0 +1,19 @@
+# 反向代理引用
+## 定义
+~~~json
+{
+  "isOn": "是否启用",
+  "isPrior": "是否覆盖上级配置，用于路由规则",
+  "reverseProxyId": "反向代理ID"
+}
+~~~
+其中：
+* `reverseProxyId` - 反向代理ID，可以通过 `/ReverseProxyService/createReverseProxy` 创建
+
+## 示例
+~~~json
+{
+  "isOn": true,
+  "reverseProxyId": 123
+}
+~~~
--- a/pkg/rpc/jsons/scheduling.md
+++ b/pkg/rpc/jsons/scheduling.md
@@ -0,0 +1,27 @@
+# 反向代理调度
+## 定义
+~~~json
+{
+	"code": "调度方法代号",
+    "options": "调度选项"
+}
+~~~
+
+其中：
+* `code` 调度方法代号
+  * `random` - 随机
+  * `roundRobin` - 轮询
+  * `hash` - Hash算法
+    * `key` - 自定义Key，可以使用请求变量，比如 `${remoteAddr}`
+  * `sticky` - Sticky算法
+    * `type` - 类型：cookie、header、argument
+    * `param` - 参数值
+
+
+## 示例
+~~~json
+{
+  "code": "random",
+  "options": null
+}
+~~~
--- a/pkg/rpc/pb/service_origin.pb.go
+++ b/pkg/rpc/pb/service_origin.pb.go
@@ -194,7 +194,7 @@ type CreateOriginResponse struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	OriginId int64 `protobuf:"varint,1,opt,name=originId,proto3" json:"originId,omitempty"`
+	OriginId int64 `protobuf:"varint,1,opt,name=originId,proto3" json:"originId,omitempty"` // 创建的源站ID
 }

 func (x *CreateOriginResponse) Reset() {
--- a/pkg/rpc/pb/service_reverse_proxy.pb.go
+++ b/pkg/rpc/pb/service_reverse_proxy.pb.go
@@ -35,9 +35,9 @@ type CreateReverseProxyRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	SchedulingJSON     []byte `protobuf:"bytes,1,opt,name=schedulingJSON,proto3" json:"schedulingJSON,omitempty"`
-	PrimaryOriginsJSON []byte `protobuf:"bytes,2,opt,name=primaryOriginsJSON,proto3" json:"primaryOriginsJSON,omitempty"`
-	BackupOriginsJSON  []byte `protobuf:"bytes,3,opt,name=backupOriginsJSON,proto3" json:"backupOriginsJSON,omitempty"`
+	SchedulingJSON     []byte `protobuf:"bytes,1,opt,name=schedulingJSON,proto3" json:"schedulingJSON,omitempty"`         // 可选项，调度设置 @link json:scheduling
+	PrimaryOriginsJSON []byte `protobuf:"bytes,2,opt,name=primaryOriginsJSON,proto3" json:"primaryOriginsJSON,omitempty"` // 可选项，主要源站 @link json:origin_refs
+	BackupOriginsJSON  []byte `protobuf:"bytes,3,opt,name=backupOriginsJSON,proto3" json:"backupOriginsJSON,omitempty"`   // 可选项，备用源站 @link json:origin_refs
 }

 func (x *CreateReverseProxyRequest) Reset() {
--- a/pkg/rpc/pb/service_server.pb.go
+++ b/pkg/rpc/pb/service_server.pb.go
@@ -35,11 +35,11 @@ type CreateServerRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	UserId      int64  `protobuf:"varint,1,opt,name=userId,proto3" json:"userId,omitempty"`          // 可选参数，用户ID，如果不想指定用户，此值可以为0
-	AdminId     int64  `protobuf:"varint,2,opt,name=adminId,proto3" json:"adminId,omitempty"`        // 可选参数，管理员ID
+	UserId      int64  `protobuf:"varint,1,opt,name=userId,proto3" json:"userId,omitempty"`          // 可选项，用户ID，如果不想指定用户，此值可以为0
+	AdminId     int64  `protobuf:"varint,2,opt,name=adminId,proto3" json:"adminId,omitempty"`        // 可选项，管理员ID
 	Type        string `protobuf:"bytes,3,opt,name=type,proto3" json:"type,omitempty"`               // 类型：httpProxy（HTTP反向代理，一般CDN服务都选这个）、httpWeb（静态文件服务，只会从服务器上读取文件内容，不会转发到源站）、tcpProxy（TCP反向代理）、udpProxy（UDP反向代理）
 	Name        string `protobuf:"bytes,4,opt,name=name,proto3" json:"name,omitempty"`               // 网站名称，通常可以是一个域名
-	Description string `protobuf:"bytes,5,opt,name=description,proto3" json:"description,omitempty"` // 可选参数，网站描述
+	Description string `protobuf:"bytes,5,opt,name=description,proto3" json:"description,omitempty"` // 可选项，网站描述
 	// 配置相关
 	ServerNamesJSON []byte `protobuf:"bytes,8,opt,name=serverNamesJSON,proto3" json:"serverNamesJSON,omitempty"` // 域名列表 @link json:server_names
 	// Deprecated: Do not use.
@@ -50,10 +50,10 @@ type CreateServerRequest struct {
 	TlsJSON          []byte  `protobuf:"bytes,12,opt,name=tlsJSON,proto3" json:"tlsJSON,omitempty"`                       // TLS协议，当type为tcpProxy时填写 @link json:tls_protocol
 	UnixJSON         []byte  `protobuf:"bytes,13,opt,name=unixJSON,proto3" json:"unixJSON,omitempty"`                     // 备用参数，不用填写
 	UdpJSON          []byte  `protobuf:"bytes,14,opt,name=udpJSON,proto3" json:"udpJSON,omitempty"`                       // UDP协议，当type为udpProxy时填写 @link json:udp_protocol
-	WebId            int64   `protobuf:"varint,15,opt,name=webId,proto3" json:"webId,omitempty"`                          // 可选参数，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
-	ReverseProxyJSON []byte  `protobuf:"bytes,16,opt,name=reverseProxyJSON,proto3" json:"reverseProxyJSON,omitempty"`     // 反向代理（包含源站）设置
-	ServerGroupIds   []int64 `protobuf:"varint,17,rep,packed,name=serverGroupIds,proto3" json:"serverGroupIds,omitempty"` // 所属网站分组ID列表
-	UserPlanId       int64   `protobuf:"varint,18,opt,name=userPlanId,proto3" json:"userPlanId,omitempty"`                // 可选参数，套餐ID
+	WebId            int64   `protobuf:"varint,15,opt,name=webId,proto3" json:"webId,omitempty"`                          // 可选项，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
+	ReverseProxyJSON []byte  `protobuf:"bytes,16,opt,name=reverseProxyJSON,proto3" json:"reverseProxyJSON,omitempty"`     // 反向代理（包含源站）配置引用，此项可以在创建网站后再设置 @link json:reverse_proxy_ref
+	ServerGroupIds   []int64 `protobuf:"varint,17,rep,packed,name=serverGroupIds,proto3" json:"serverGroupIds,omitempty"` // 可选项，所属网站分组ID列表
+	UserPlanId       int64   `protobuf:"varint,18,opt,name=userPlanId,proto3" json:"userPlanId,omitempty"`                // 可选项，套餐ID
 	NodeClusterId    int64   `protobuf:"varint,30,opt,name=nodeClusterId,proto3" json:"nodeClusterId,omitempty"`          // 所部署的集群ID
 	IncludeNodesJSON []byte  `protobuf:"bytes,31,opt,name=includeNodesJSON,proto3" json:"includeNodesJSON,omitempty"`     // 备用参数，不用填写
 	ExcludeNodesJSON []byte  `protobuf:"bytes,32,opt,name=excludeNodesJSON,proto3" json:"excludeNodesJSON,omitempty"`     // 备用参数，不用填写
--- a/pkg/rpc/protos/service_origin.proto
+++ b/pkg/rpc/protos/service_origin.proto
@@ -42,7 +42,7 @@ message CreateOriginRequest {
 }

 message CreateOriginResponse {
-	int64 originId = 1;
+	int64 originId = 1; // 创建的源站ID
 }

 // 修改源站
--- a/pkg/rpc/protos/service_reverse_proxy.proto
+++ b/pkg/rpc/protos/service_reverse_proxy.proto
@@ -32,9 +32,9 @@ service ReverseProxyService {

 // 创建反向代理
 message CreateReverseProxyRequest {
-	bytes schedulingJSON = 1;
-	bytes primaryOriginsJSON = 2;
-	bytes backupOriginsJSON = 3;
+	bytes schedulingJSON = 1; // 可选项，调度设置 @link json:scheduling
+	bytes primaryOriginsJSON = 2; // 可选项，主要源站 @link json:origin_refs
+	bytes backupOriginsJSON = 3; // 可选项，备用源站 @link json:origin_refs
 }

 message CreateReverseProxyResponse {
--- a/pkg/rpc/protos/service_server.proto
+++ b/pkg/rpc/protos/service_server.proto
@@ -179,11 +179,11 @@ service ServerService {

 // 创建网站
 message CreateServerRequest {
-	int64 userId = 1; // 可选参数，用户ID，如果不想指定用户，此值可以为0
-	int64 adminId = 2; // 可选参数，管理员ID
+	int64 userId = 1; // 可选项，用户ID，如果不想指定用户，此值可以为0
+	int64 adminId = 2; // 可选项，管理员ID
 	string type = 3; // 类型：httpProxy（HTTP反向代理，一般CDN服务都选这个）、httpWeb（静态文件服务，只会从服务器上读取文件内容，不会转发到源站）、tcpProxy（TCP反向代理）、udpProxy（UDP反向代理）
 	string name = 4; // 网站名称，通常可以是一个域名
-	string description = 5; // 可选参数，网站描述
+	string description = 5; // 可选项，网站描述

 	// 配置相关
 	bytes serverNamesJSON = 8; // 域名列表 @link json:server_names
@@ -194,10 +194,10 @@ message CreateServerRequest {
 	bytes tlsJSON = 12;  // TLS协议，当type为tcpProxy时填写 @link json:tls_protocol
 	bytes unixJSON = 13; // 备用参数，不用填写
 	bytes udpJSON = 14; // UDP协议，当type为udpProxy时填写 @link json:udp_protocol
-	int64 webId = 15; // 可选参数，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
-	bytes reverseProxyJSON = 16; // 反向代理（包含源站）设置
-	repeated int64 serverGroupIds = 17; // 所属网站分组ID列表
-	int64 userPlanId = 18; // 可选参数，套餐ID
+	int64 webId = 15; // 可选项，Web配置ID，当type为httpProxy或者httpWeb时填写，可以通过 /HTTPWebService/createHTTPWeb 接口创建；如果你需要配置缓存等信息时需要在 HTTPWebService 接口操作
+	bytes reverseProxyJSON = 16; // 反向代理（包含源站）配置引用，此项可以在创建网站后再设置 @link json:reverse_proxy_ref
+	repeated int64 serverGroupIds = 17; // 可选项，所属网站分组ID列表
+	int64 userPlanId = 18; // 可选项，套餐ID

 	int64 nodeClusterId = 30; // 所部署的集群ID
 	bytes includeNodesJSON = 31; // 备用参数，不用填写