feat: add API versioning , translate swagger, remove rate limiter

docs/swagger.yaml

@@ -1,3 +1,4 @@
+basePath: /api/v1
 definitions:
   auth.AuthResponse:
     properties:
@@ -125,6 +126,10 @@ definitions:
     type: object
   org.OrgListResponse:
     properties:
+      limit:
+        type: integer
+      offset:
+        type: integer
       organizations:
         items:
           $ref: '#/definitions/org.Organization'
@@ -162,17 +167,21 @@ definitions:
     type: object
 info:
   contact: {}
-  description: API for AegisGuard control plane
+  description: |-
+    API системы управления AegisGuard. Позволяет управлять пользователями и организациями.
+    Все защищённые эндпоинты требуют заголовок `Authorization: Bearer <token>`.
+    Токен получается при регистрации или входе.
   title: AegisGuard API
   version: "1.0"
 paths:
-  /api/auth/login:
+  /api/v1/auth/login:
     post:
       consumes:
       - application/json
-      description: Authenticate user with email and password, returns JWT token
+      description: Аутентификация по email и паролю. Возвращает access_token (JWT)
+        и refresh_token.
       parameters:
-      - description: Login credentials
+      - description: Email и пароль
         in: body
         name: request
         required: true
@@ -182,27 +191,28 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Успешный вход, токены в ответе
           schema:
             $ref: '#/definitions/auth.AuthResponse'
         "400":
-          description: Bad Request
+          description: Ошибка валидации полей
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
         "401":
-          description: Unauthorized
+          description: Неверный email или пароль
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
-      summary: Login
+      summary: Вход
       tags:
       - auth
-  /api/auth/logout:
+  /api/v1/auth/logout:
     post:
       consumes:
       - application/json
-      description: Invalidate a refresh token (logout)
+      description: Аннулирование refresh_token. После выхода повторное использование
+        того же refresh_token вернёт 401.
       parameters:
-      - description: Refresh token to invalidate
+      - description: Refresh_token для аннулирования
         in: body
         name: request
         required: true
@@ -212,49 +222,53 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: '{"message": "logged out successfully"}'
           schema:
             additionalProperties:
               type: string
             type: object
         "400":
-          description: Bad Request
+          description: Не указан refresh_token
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
         "401":
-          description: Unauthorized
+          description: Refresh_token не найден или уже аннулирован
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
-      summary: Logout
+      summary: Выход
       tags:
       - auth
-  /api/auth/me:
+  /api/v1/auth/me:
     get:
       consumes:
       - application/json
-      description: Get authenticated user's profile
+      description: |-
+        Получение профиля текущего авторизованного пользователя.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
       produces:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Данные пользователя
           schema:
             $ref: '#/definitions/auth.UserResponse'
         "401":
-          description: Unauthorized
+          description: Токен не указан или недействителен
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
       security:
       - Bearer: []
-      summary: Get current user
+      summary: Профиль пользователя
       tags:
       - auth
     put:
       consumes:
       - application/json
-      description: Update current user's username
+      description: |-
+        Обновление username текущего пользователя.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
       parameters:
-      - description: Profile update
+      - description: Новый username
         in: body
         name: request
         required: true
@@ -264,29 +278,32 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Обновлённый профиль
           schema:
             $ref: '#/definitions/auth.UserResponse'
         "400":
-          description: Bad Request
+          description: 'Ошибка валидации: username от 3 до 30 символов'
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
         "401":
-          description: Unauthorized
+          description: Токен не указан или недействителен
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
       security:
       - Bearer: []
-      summary: Update profile
+      summary: Обновление профиля
       tags:
       - auth
-  /api/auth/password:
+  /api/v1/auth/password:
     put:
       consumes:
       - application/json
-      description: Change current user's password
+      description: |-
+        Изменение пароля текущего пользователя. Требуется указать старый и новый пароль.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
+        Пароль должен содержать минимум 8 символов, заглавную букву, строчную букву и цифру.
       parameters:
-      - description: Password change details
+      - description: Старый и новый пароль
         in: body
         name: request
         required: true
@@ -296,31 +313,34 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: '{"message": "password changed successfully"}'
           schema:
             additionalProperties:
               type: string
             type: object
         "400":
-          description: Bad Request
+          description: 'Ошибка валидации: неверный старый пароль, слабый новый или
+            совпадают'
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
         "401":
-          description: Unauthorized
+          description: Токен не указан или недействителен
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
       security:
       - Bearer: []
-      summary: Change password
+      summary: Смена пароля
       tags:
       - auth
-  /api/auth/refresh:
+  /api/v1/auth/refresh:
     post:
       consumes:
       - application/json
-      description: Get a new access token using a refresh token
+      description: |-
+        Получение новой пары токенов по refresh_token. Старый refresh_token становится недействительным (ротация).
+        Если refresh_token истёк или уже был использован — придёт 401.
       parameters:
-      - description: Refresh token
+      - description: Действительный refresh_token
         in: body
         name: request
         required: true
@@ -330,27 +350,29 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Новая пара токенов
           schema:
             $ref: '#/definitions/auth.AuthResponse'
         "400":
-          description: Bad Request
+          description: Не указан refresh_token
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
         "401":
-          description: Unauthorized
+          description: Refresh_token недействителен или истёк
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
-      summary: Refresh token
+      summary: Обновление токенов
       tags:
       - auth
-  /api/auth/register:
+  /api/v1/auth/register:
     post:
       consumes:
       - application/json
-      description: Create user account with username, email, password
+      description: |-
+        Создание новой учётной записи. После успешной регистрации сразу возвращается access_token и refresh_token.
+        Пароль должен содержать минимум 8 символов, заглавную букву, строчную букву и цифру.
       parameters:
-      - description: Registration details
+      - description: Данные для регистрации
         in: body
         name: request
         required: true
@@ -360,47 +382,60 @@ paths:
       - application/json
       responses:
         "201":
-          description: Created
+          description: Пользователь создан, токены в ответе
           schema:
             $ref: '#/definitions/auth.AuthResponse'
         "400":
-          description: Bad Request
+          description: Ошибка валидации полей (некорректный email, слабый пароль)
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
         "409":
-          description: Conflict
+          description: Email уже зарегистрирован
           schema:
             $ref: '#/definitions/auth.ErrorResponse'
-      summary: Register
+      summary: Регистрация
       tags:
       - auth
-  /api/organizations:
+  /api/v1/organizations:
     get:
       consumes:
       - application/json
-      description: Get all organizations
+      description: |-
+        Получение списка всех организаций с пагинацией.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
+      parameters:
+      - description: Количество записей на странице (по умолчанию 20)
+        in: query
+        name: limit
+        type: integer
+      - description: Смещение от начала списка (по умолчанию 0)
+        in: query
+        name: offset
+        type: integer
       produces:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Список организаций
           schema:
             $ref: '#/definitions/org.OrgListResponse'
         "500":
-          description: Internal Server Error
+          description: Внутренняя ошибка сервера
           schema:
             $ref: '#/definitions/org.ErrorResponse'
       security:
       - Bearer: []
-      summary: List organizations
+      summary: Список организаций
       tags:
       - organizations
     post:
       consumes:
       - application/json
-      description: Create a new organization
+      description: |-
+        Создание новой организации. slug используется в URL и должен быть уникальным.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
       parameters:
-      - description: Organization details
+      - description: Название и slug организации
         in: body
         name: request
         required: true
@@ -410,29 +445,31 @@ paths:
       - application/json
       responses:
         "201":
-          description: Created
+          description: Организация создана
           schema:
             $ref: '#/definitions/org.OrgResponse'
         "400":
-          description: Bad Request
+          description: Ошибка валидации полей
           schema:
             $ref: '#/definitions/org.ErrorResponse'
         "409":
-          description: Conflict
+          description: Slug уже занят
           schema:
             $ref: '#/definitions/org.ErrorResponse'
       security:
       - Bearer: []
-      summary: Create organization
+      summary: Создание организации
       tags:
       - organizations
-  /api/organizations/{id}:
+  /api/v1/organizations/{id}:
     delete:
       consumes:
       - application/json
-      description: Delete an organization
+      description: |-
+        Безвозвратное удаление организации по её ID.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
       parameters:
-      - description: Organization ID
+      - description: UUID организации
         in: path
         name: id
         required: true
@@ -441,26 +478,28 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: '{"message": "organization deleted"}'
           schema:
             additionalProperties:
               type: string
             type: object
         "404":
-          description: Not Found
+          description: Организация не найдена
           schema:
             $ref: '#/definitions/org.ErrorResponse'
       security:
       - Bearer: []
-      summary: Delete organization
+      summary: Удаление организации
       tags:
       - organizations
     get:
       consumes:
       - application/json
-      description: Get organization details
+      description: |-
+        Получение информации об организации по её ID.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
       parameters:
-      - description: Organization ID
+      - description: UUID организации
         in: path
         name: id
         required: true
@@ -469,29 +508,31 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Данные организации
           schema:
             $ref: '#/definitions/org.OrgResponse'
         "404":
-          description: Not Found
+          description: Организация не найдена
           schema:
             $ref: '#/definitions/org.ErrorResponse'
       security:
       - Bearer: []
-      summary: Get organization by ID
+      summary: Получить организацию
       tags:
       - organizations
     put:
       consumes:
       - application/json
-      description: Update organization name
+      description: |-
+        Обновление названия организации. slug изменить нельзя.
+        **Требуется:** заголовок `Authorization: Bearer <token>`.
       parameters:
-      - description: Organization ID
+      - description: UUID организации
         in: path
         name: id
         required: true
         type: string
-      - description: New organization details
+      - description: Новое название организации
         in: body
         name: request
         required: true
@@ -501,27 +542,28 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: Обновлённая организация
           schema:
             $ref: '#/definitions/org.OrgResponse'
         "400":
-          description: Bad Request
+          description: Ошибка валидации полей
           schema:
             $ref: '#/definitions/org.ErrorResponse'
         "404":
-          description: Not Found
+          description: Организация не найдена
           schema:
             $ref: '#/definitions/org.ErrorResponse'
       security:
       - Bearer: []
-      summary: Update organization
+      summary: Обновление организации
       tags:
       - organizations
 schemes:
 - http
 securityDefinitions:
   Bearer:
-    description: Type "Bearer" followed by a space and the JWT token.
+    description: Введите `Bearer <token>`, где token — access_token из ответа /auth/login
+      или /auth/register
     in: header
     name: Authorization
     type: apiKey