docs: improve comments in security proto

The existing comments did not match the service definition (they look like copy paste from another service). I also added a little bit more comments for the fields in the request and response. Signed-off-by: Tomasz Zurkowski <zurkowski@google.com> Signed-off-by: Andrey Smirnov <andrey.smirnov@talos-systems.com>
siderolabs · Mar 16, 2022 · cc7719c · cc7719c
1 parent caf800f
commit cc7719c
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 10 deletions.
diff --git a/api/security/security.proto b/api/security/security.proto
@@ -9,13 +9,16 @@ service SecurityService {
   rpc Certificate(CertificateRequest) returns (CertificateResponse);
 }
 
-// The request message containing the process name.
+// The request message containing the certificate signing request.
 message CertificateRequest {
+  // Certificate Signing Request in PEM format.
   bytes csr = 1;
 }
 
-// The response message containing the requested logs.
+// The response message containing signed certificate.
 message CertificateResponse {
+  // Certificate of the CA that signed the requested certificate in PEM format.
   bytes ca = 1;
+  // Signed X.509 requested certificate in PEM format.
   bytes crt = 2;
 }
diff --git a/pkg/machinery/api/security/security.pb.go b/pkg/machinery/api/security/security.pb.go
diff --git a/website/content/docs/v1.0/Reference/api.md b/website/content/docs/v1.0/Reference/api.md
@@ -3067,12 +3067,12 @@ ResourceService provides user-facing API for the Talos resources.
 <a name="securityapi.CertificateRequest"></a>
 
 ### CertificateRequest
-The request message containing the process name.
+The request message containing the certificate signing request.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| csr | [bytes](#bytes) |  |  |
+| csr | [bytes](#bytes) |  | Certificate Signing Request in PEM format. |
 
 
 
@@ -3082,13 +3082,13 @@ The request message containing the process name.
 <a name="securityapi.CertificateResponse"></a>
 
 ### CertificateResponse
-The response message containing the requested logs.
+The response message containing signed certificate.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ca | [bytes](#bytes) |  |  |
-| crt | [bytes](#bytes) |  |  |
+| ca | [bytes](#bytes) |  | Certificate of the CA that signed the requested certificate in PEM format. |
+| crt | [bytes](#bytes) |  | Signed X.509 requested certificate in PEM format. |