From 10a9a2bcd60436f116dc8452c4a7b3290b04400e Mon Sep 17 00:00:00 2001
From: Dmitry Ryabov <dm.al.ryabov@gmail.com>
Date: Wed, 24 Aug 2022 18:04:14 +0300
Subject: [PATCH] update api documentation (#4)

---
 proto/v1/auth.proto | 58 ++++++++++++++++++++++++++++++++-------------
 proto/v1/key.proto  |  8 ++++++-
 2 files changed, 49 insertions(+), 17 deletions(-)

diff --git a/proto/v1/auth.proto b/proto/v1/auth.proto
index 98ca5c2..e92c5a5 100644
--- a/proto/v1/auth.proto
+++ b/proto/v1/auth.proto
@@ -4,10 +4,21 @@ package beget.auth.v1.auth;
 
 import "google/api/annotations.proto";
 
-// Сервис аутентификации, выдает JWT токены для доступа к cp.beget.com/api.beget.com
+// Аутентификация
+//
+// Сервис предоставляет набор методов для работы с токеном аутентификации, используемом для
+// доступа в панель управления и к API: cp.beget.com и api.beget.com
 service AuthService {
     // Получить JWT токен
-    rpc auth (AuthRequest) returns (AuthResponse) {
+    //
+    // Выполняет вход в аккаунт и выдает JWT токен, который далее может быть использован для аутентификации запросов в API.
+    //
+    // При отключенной двухфакторной аутентификации (2FA) поле `code` не используется и не должно передаваться в запросе.
+    //
+    // При включенной двухфакторной аутентификации (2FA) первоначальный запрос к данному методу вернет ошибку с кодом
+    // `CODE_REQUIRED_EMAIL` или `CODE_REQUIRED_SMS`, а на соответствующий адрес 2FA придет код. Для получения токена
+    // необходимо выполнить повторный запрос этого же метода, добавив к уже введенным данным полученный код в поле `code`.
+    rpc auth(AuthRequest) returns (AuthResponse) {
         option (google.api.http) = {
 			post: "/v1/auth"
 			body: "*"
@@ -15,22 +26,35 @@ service AuthService {
     }
 
     // Обновить JWT токен
-    rpc refreshToken (RefreshTokenRequest) returns (RefreshTokenResponse) {
+    //
+    // Продлевает действие текущего JWT токена.
+    rpc refreshToken(RefreshTokenRequest) returns (RefreshTokenResponse) {
         option (google.api.http) = {
 			post: "/v1/auth/refresh"
 		};
     }
 
     // Получить JWT токен подчиненного аккаунта
-    rpc switchUser (SwitchUserRequest) returns (SwitchUserResponse) {
+    //
+    // Выполняет вход в аккаунт, входящий в группу мульти-аккаунтов, и выдает для него JWT токен,
+    // который далее может быть использован для аутентификации запросов в API.
+    //
+    // При отключенной двухфакторной аутентификации (2FA) на подчиненном аккаунте поле `code` не используется
+    // и не должно передаваться в запросе.
+    //
+    // При включенной двухфакторной аутентификации (2FA) на подчиненном аккаунте, поле `code` действует таким же
+    // образом, как одноименное поле в методе "Получить JWT токен" из API "Аутентификация".
+    rpc switchUser(SwitchUserRequest) returns (SwitchUserResponse) {
         option (google.api.http) = {
 			post: "/v1/auth/switch"
 			body: "*"
 		};
     }
 
-    // Отозвать JWT токен(logout)
-    rpc logout (LogoutRequest) returns (LogoutResponse) {
+    // Отозвать JWT токен
+    //
+    // Отзывает JWT токен, делая его невалидным для дальнейших запросов.
+    rpc logout(LogoutRequest) returns (LogoutResponse) {
         option (google.api.http) = {
 			post: "/v1/auth/logout"
 		};
@@ -44,7 +68,7 @@ message AuthRequest {
     // Пароль
     string password = 2;
 
-    // Код двухфакторной аутентификации
+    // Код двухфакторной аутентификации (необязательное поле, см. описание метода)
     string code = 3;
 
     // Выдать токен на 1 год
@@ -52,15 +76,15 @@ message AuthRequest {
 }
 
 message AuthResponse {
+    // Результат запроса
     oneof response {
-        // JWT токен
+        // Результат запроса: JWT токен
         string token = 1;
 
-        // Ошибка аутентификации
+        // Результат запроса: ошибка аутентификации
         ErrorStatus error = 2;
     }
 
-
     enum ErrorStatus {
         // Внутрення ошибка
         INTERNAL_ERROR = 0;
@@ -110,16 +134,17 @@ message SwitchUserRequest {
     // Пароль
     string password = 2;
 
-    // Код двухфакторной аутентификации
+    // Код двухфакторной аутентификации (необязательное поле, см. описание метода)
     string code = 3;
 }
 
 message SwitchUserResponse {
+    // Результат запроса
     oneof response {
-        // JWT Токен
+        // Результат запроса: JWT Токен
         string token = 1;
 
-        // Ошибка при получении токена
+        // Результат запроса: ошибка при получении токена
         ErrorStatus error = 2;
     }
 
@@ -175,11 +200,12 @@ message RefreshTokenRequest {
 }
 
 message RefreshTokenResponse {
+    // Результат запроса
     oneof response {
-        // JWT Токен
+        // Результат запроса: JWT Токен
         string token = 1;
 
-        // Ошибка при обновлении токена
+        // Результат запроса: ошибка при обновлении токена
         ErrorStatus error = 2;
     }
 
@@ -208,4 +234,4 @@ message LogoutRequest {
 }
 
 message LogoutResponse {
-}
\ No newline at end of file
+}
diff --git a/proto/v1/key.proto b/proto/v1/key.proto
index cad81fb..6903d22 100644
--- a/proto/v1/key.proto
+++ b/proto/v1/key.proto
@@ -4,9 +4,15 @@ package beget.auth.v1.key;
 
 import "google/api/annotations.proto";
 
+// Публичный ключ
+//
+// Сервис предоставляет метод для получения публичной части ключа, используемого для подписи JWT данного API.
 service KeyService {
     // Получить публичный ключ
-    rpc getKey (GetKeyRequest) returns (GetKeyResponse) {
+    //
+    // Возвращает публичный ключ, который может быть использован для проверки валидности подписи JWT,
+    // полученного в методах из API "Аутентификация".
+    rpc getKey(GetKeyRequest) returns (GetKeyResponse) {
         option (google.api.http) = {
 			get: "/v1/auth/key"
 		};