增加API注释

2025-11-03 12:20:27 +08:00 · 2023-07-01 19:27:49 +08:00
parent 705ffcd087
commit 52ed467580
4 changed files with 82 additions and 47 deletions
--- a/build/rpc.json
+++ b/build/rpc.json
@@ -14602,7 +14602,7 @@
    },
    {
      "name": "CreateAPINodeRequest",
-      "code": "message CreateAPINodeRequest {\n\tstring name = 1;\n\tstring description = 2;\n\tbytes httpJSON = 3;\n\tbytes httpsJSON = 4;\n\tbytes accessAddrsJSON = 5;\n\tbool isOn = 6;\n\tbool restIsOn = 7;\n\tbytes restHTTPJSON = 8;\n\tbytes restHTTPSJSON = 9;\n}",
+      "code": "message CreateAPINodeRequest {\n\tstring name = 1; // API节点名称\n\tstring description = 2; // API节点描述\n\tbytes httpJSON = 3; // 监听HTTP地址配置 @link json:http_protocol\n\tbytes httpsJSON = 4; // 监听HTTPS地址配置 @link json:https_protocol\n\tbytes accessAddrsJSON = 5; // 访问地址 @link json:network_address\n\tbool isOn = 6; // 是否启用当前API节点\n\tbool restIsOn = 7; // 是否启用API\n\tbytes restHTTPJSON = 8; // API地址HTTP地址配置 @link json:http_protocol\n\tbytes restHTTPSJSON = 9;  // API地址HTTPS地址配置 @link json:https_protocol\n}",
      "doc": "创建API节点"
    },
    {
@@ -17477,7 +17477,7 @@
    },
    {
      "name": "FindCurrentAPINodeVersionResponse",
-      "code": "message FindCurrentAPINodeVersionResponse {\n\tstring version = 1; // 版本号\n\tstring os = 2; // 系统代号，比如linux\n\tstring arch = 3; // 架构\n\tstring role = 4; // 角色\n}",
+      "code": "message FindCurrentAPINodeVersionResponse {\n\tstring version = 1; // 版本号\n\tstring os = 2; // 系统代号，比如linux\n\tstring arch = 3; // 架构，比如amd64\n\tstring role = 4; // 角色，通常为api\n}",
      "doc": ""
    },
    {
@@ -21502,7 +21502,7 @@
    },
    {
      "name": "UpdateAPINodeRequest",
-      "code": "message UpdateAPINodeRequest {\n\tint64 apiNodeId = 1;\n\tstring name = 2;\n\tstring description = 3;\n\tbytes httpJSON = 4;\n\tbytes httpsJSON = 5;\n\tbytes accessAddrsJSON = 6;\n\tbool isOn = 7;\n\tbool restIsOn = 8;\n\tbytes restHTTPJSON = 9;\n\tbytes restHTTPSJSON = 10;\n\tbool isPrimary = 11;\n}",
+      "code": "message UpdateAPINodeRequest {\n\tint64 apiNodeId = 1; // API节点ID\n\tstring name = 2; // API节点名称\n\tstring description = 3; // API节点描述\n\tbytes httpJSON = 4; // 监听HTTP地址配置 @link json:http_protocol\n\tbytes httpsJSON = 5; // 监听HTTPS地址配置 @link json:https_protocol\n\tbytes accessAddrsJSON = 6; // 访问地址 @link json:network_address\n\tbool isOn = 7; // 是否启用当前API节点\n\tbool restIsOn = 8; // 是否启用API\n\tbytes restHTTPJSON = 9; // API地址HTTP地址配置 @link json:http_protocol\n\tbytes restHTTPSJSON = 10; // API地址HTTPS地址配置 @link json:https_protocol\n\tbool isPrimary = 11; // 是否为主要API节点，日常任务主要运行在主要API节点上\n}",
      "doc": "修改API节点"
    },
    {
@@ -22907,6 +22907,10 @@
      "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:network_address",
+      "content": "# 网络地址定义\n\n## 定义\n~~~json\n{\n\t\"protocol\": \"协议\",\n\t\"host\": \"主机地址，通常为空\",\n\t\"portRange\": \"端口或者端口范围\"\n}\n~~~\n\n## 示例\n对于 `http://example.com`：\n~~~json\n{\n  \"protocol\": \"http\",\n  \"host\": \"example.com\",\n  \"portRange\": \"80\"\n}\n~~~\n\n\n对于 `https://example.com`：\n~~~json\n{\n  \"protocol\": \"https\",\n  \"host\": \"example.com\",\n  \"portRange\": \"443\"\n}\n~~~\n"
+    },
    {
      "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~~~"
--- a/pkg/rpc/jsons/network_address.md
+++ b/pkg/rpc/jsons/network_address.md
@@ -0,0 +1,30 @@
+# 网络地址定义
+
+## 定义
+~~~json
+{
+	"protocol": "协议",
+	"host": "主机地址，通常为空",
+	"portRange": "端口或者端口范围"
+}
+~~~
+
+## 示例
+对于 `http://example.com`：
+~~~json
+{
+  "protocol": "http",
+  "host": "example.com",
+  "portRange": "80"
+}
+~~~
+
+
+对于 `https://example.com`：
+~~~json
+{
+  "protocol": "https",
+  "host": "example.com",
+  "portRange": "443"
+}
+~~~
--- a/pkg/rpc/pb/service_api_node.pb.go
+++ b/pkg/rpc/pb/service_api_node.pb.go
@@ -35,15 +35,15 @@ type CreateAPINodeRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	Name            string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
-	Description     string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
-	HttpJSON        []byte `protobuf:"bytes,3,opt,name=httpJSON,proto3" json:"httpJSON,omitempty"`
-	HttpsJSON       []byte `protobuf:"bytes,4,opt,name=httpsJSON,proto3" json:"httpsJSON,omitempty"`
-	AccessAddrsJSON []byte `protobuf:"bytes,5,opt,name=accessAddrsJSON,proto3" json:"accessAddrsJSON,omitempty"`
-	IsOn            bool   `protobuf:"varint,6,opt,name=isOn,proto3" json:"isOn,omitempty"`
-	RestIsOn        bool   `protobuf:"varint,7,opt,name=restIsOn,proto3" json:"restIsOn,omitempty"`
-	RestHTTPJSON    []byte `protobuf:"bytes,8,opt,name=restHTTPJSON,proto3" json:"restHTTPJSON,omitempty"`
-	RestHTTPSJSON   []byte `protobuf:"bytes,9,opt,name=restHTTPSJSON,proto3" json:"restHTTPSJSON,omitempty"`
+	Name            string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`                       // API节点名称
+	Description     string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`         // API节点描述
+	HttpJSON        []byte `protobuf:"bytes,3,opt,name=httpJSON,proto3" json:"httpJSON,omitempty"`               // 监听HTTP地址配置 @link json:http_protocol
+	HttpsJSON       []byte `protobuf:"bytes,4,opt,name=httpsJSON,proto3" json:"httpsJSON,omitempty"`             // 监听HTTPS地址配置 @link json:https_protocol
+	AccessAddrsJSON []byte `protobuf:"bytes,5,opt,name=accessAddrsJSON,proto3" json:"accessAddrsJSON,omitempty"` // 访问地址 @link json:network_address
+	IsOn            bool   `protobuf:"varint,6,opt,name=isOn,proto3" json:"isOn,omitempty"`                      // 是否启用当前API节点
+	RestIsOn        bool   `protobuf:"varint,7,opt,name=restIsOn,proto3" json:"restIsOn,omitempty"`              // 是否启用API
+	RestHTTPJSON    []byte `protobuf:"bytes,8,opt,name=restHTTPJSON,proto3" json:"restHTTPJSON,omitempty"`       // API地址HTTP地址配置 @link json:http_protocol
+	RestHTTPSJSON   []byte `protobuf:"bytes,9,opt,name=restHTTPSJSON,proto3" json:"restHTTPSJSON,omitempty"`     // API地址HTTPS地址配置 @link json:https_protocol
 }

 func (x *CreateAPINodeRequest) Reset() {
@@ -194,17 +194,17 @@ type UpdateAPINodeRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields

-	ApiNodeId       int64  `protobuf:"varint,1,opt,name=apiNodeId,proto3" json:"apiNodeId,omitempty"`
-	Name            string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
-	Description     string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
-	HttpJSON        []byte `protobuf:"bytes,4,opt,name=httpJSON,proto3" json:"httpJSON,omitempty"`
-	HttpsJSON       []byte `protobuf:"bytes,5,opt,name=httpsJSON,proto3" json:"httpsJSON,omitempty"`
-	AccessAddrsJSON []byte `protobuf:"bytes,6,opt,name=accessAddrsJSON,proto3" json:"accessAddrsJSON,omitempty"`
-	IsOn            bool   `protobuf:"varint,7,opt,name=isOn,proto3" json:"isOn,omitempty"`
-	RestIsOn        bool   `protobuf:"varint,8,opt,name=restIsOn,proto3" json:"restIsOn,omitempty"`
-	RestHTTPJSON    []byte `protobuf:"bytes,9,opt,name=restHTTPJSON,proto3" json:"restHTTPJSON,omitempty"`
-	RestHTTPSJSON   []byte `protobuf:"bytes,10,opt,name=restHTTPSJSON,proto3" json:"restHTTPSJSON,omitempty"`
-	IsPrimary       bool   `protobuf:"varint,11,opt,name=isPrimary,proto3" json:"isPrimary,omitempty"`
+	ApiNodeId       int64  `protobuf:"varint,1,opt,name=apiNodeId,proto3" json:"apiNodeId,omitempty"`            // API节点ID
+	Name            string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`                       // API节点名称
+	Description     string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`         // API节点描述
+	HttpJSON        []byte `protobuf:"bytes,4,opt,name=httpJSON,proto3" json:"httpJSON,omitempty"`               // 监听HTTP地址配置 @link json:http_protocol
+	HttpsJSON       []byte `protobuf:"bytes,5,opt,name=httpsJSON,proto3" json:"httpsJSON,omitempty"`             // 监听HTTPS地址配置 @link json:https_protocol
+	AccessAddrsJSON []byte `protobuf:"bytes,6,opt,name=accessAddrsJSON,proto3" json:"accessAddrsJSON,omitempty"` // 访问地址 @link json:network_address
+	IsOn            bool   `protobuf:"varint,7,opt,name=isOn,proto3" json:"isOn,omitempty"`                      // 是否启用当前API节点
+	RestIsOn        bool   `protobuf:"varint,8,opt,name=restIsOn,proto3" json:"restIsOn,omitempty"`              // 是否启用API
+	RestHTTPJSON    []byte `protobuf:"bytes,9,opt,name=restHTTPJSON,proto3" json:"restHTTPJSON,omitempty"`       // API地址HTTP地址配置 @link json:http_protocol
+	RestHTTPSJSON   []byte `protobuf:"bytes,10,opt,name=restHTTPSJSON,proto3" json:"restHTTPSJSON,omitempty"`    // API地址HTTPS地址配置 @link json:https_protocol
+	IsPrimary       bool   `protobuf:"varint,11,opt,name=isPrimary,proto3" json:"isPrimary,omitempty"`           // 是否为主要API节点，日常任务主要运行在主要API节点上
 }

 func (x *UpdateAPINodeRequest) Reset() {
@@ -772,8 +772,8 @@ type FindCurrentAPINodeVersionResponse struct {

 	Version string `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"` // 版本号
 	Os      string `protobuf:"bytes,2,opt,name=os,proto3" json:"os,omitempty"`           // 系统代号，比如linux
-	Arch    string `protobuf:"bytes,3,opt,name=arch,proto3" json:"arch,omitempty"`       // 架构
-	Role    string `protobuf:"bytes,4,opt,name=role,proto3" json:"role,omitempty"`       // 角色
+	Arch    string `protobuf:"bytes,3,opt,name=arch,proto3" json:"arch,omitempty"`       // 架构，比如amd64
+	Role    string `protobuf:"bytes,4,opt,name=role,proto3" json:"role,omitempty"`       // 角色，通常为api
 }

 func (x *FindCurrentAPINodeVersionResponse) Reset() {
--- a/pkg/rpc/protos/service_api_node.proto
+++ b/pkg/rpc/protos/service_api_node.proto
@@ -51,19 +51,20 @@ service APINodeService {

 	// 查找已有节点安装文件信息
 	rpc findLatestDeployFiles(FindLatestDeployFilesRequest) returns (FindLatestDeployFilesResponse);
+
 }

 // 创建API节点
 message CreateAPINodeRequest {
-	string name = 1;
-	string description = 2;
-	bytes httpJSON = 3;
-	bytes httpsJSON = 4;
-	bytes accessAddrsJSON = 5;
-	bool isOn = 6;
-	bool restIsOn = 7;
-	bytes restHTTPJSON = 8;
-	bytes restHTTPSJSON = 9;
+	string name = 1; // API节点名称
+	string description = 2; // API节点描述
+	bytes httpJSON = 3; // 监听HTTP地址配置 @link json:http_protocol
+	bytes httpsJSON = 4; // 监听HTTPS地址配置 @link json:https_protocol
+	bytes accessAddrsJSON = 5; // 访问地址 @link json:network_address
+	bool isOn = 6; // 是否启用当前API节点
+	bool restIsOn = 7; // 是否启用API
+	bytes restHTTPJSON = 8; // API地址HTTP地址配置 @link json:http_protocol
+	bytes restHTTPSJSON = 9;  // API地址HTTPS地址配置 @link json:https_protocol
 }

 message CreateAPINodeResponse {
@@ -72,17 +73,17 @@ message CreateAPINodeResponse {

 // 修改API节点
 message UpdateAPINodeRequest {
-	int64 apiNodeId = 1;
-	string name = 2;
-	string description = 3;
-	bytes httpJSON = 4;
-	bytes httpsJSON = 5;
-	bytes accessAddrsJSON = 6;
-	bool isOn = 7;
-	bool restIsOn = 8;
-	bytes restHTTPJSON = 9;
-	bytes restHTTPSJSON = 10;
-	bool isPrimary = 11;
+	int64 apiNodeId = 1; // API节点ID
+	string name = 2; // API节点名称
+	string description = 3; // API节点描述
+	bytes httpJSON = 4; // 监听HTTP地址配置 @link json:http_protocol
+	bytes httpsJSON = 5; // 监听HTTPS地址配置 @link json:https_protocol
+	bytes accessAddrsJSON = 6; // 访问地址 @link json:network_address
+	bool isOn = 7; // 是否启用当前API节点
+	bool restIsOn = 8; // 是否启用API
+	bytes restHTTPJSON = 9; // API地址HTTP地址配置 @link json:http_protocol
+	bytes restHTTPSJSON = 10; // API地址HTTPS地址配置 @link json:https_protocol
+	bool isPrimary = 11; // 是否为主要API节点，日常任务主要运行在主要API节点上
 }

 // 删除API节点
@@ -136,8 +137,8 @@ message FindCurrentAPINodeVersionRequest {
 message FindCurrentAPINodeVersionResponse {
 	string version = 1; // 版本号
 	string os = 2; // 系统代号，比如linux
-	string arch = 3; // 架构
-	string role = 4; // 角色
+	string arch = 3; // 架构，比如amd64
+	string role = 4; // 角色，通常为api
 }

 // 获取当前API节点的信息