openapi: 3.0.0
info:
  title: Пример описания API 
  version: 1.0.0
servers:
- url: https://example.ru/api/v1
paths:
  /organization/{organizationId}:
    get:
      tags: 
        - Работа с организациями
      summary: Получить информацию об организации
      operationId: getOrgInfo
      parameters:
        - name: organizationId
          in: path
          description: Уникальный идентификатор организации
          required: true
          schema:
            type: number
            minimum: 1
            maximum: 500
          example: "102"
      responses:
        '200':
          description: ОК 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getOrganizationInfo'
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Ресурс не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      tags:
        - Работа с организациями
      summary: Удалить организацию
      operationId: deleteOrg
      parameters:
        - name: organizationId
          in: path
          description: Уникальный идентификатор организации
          required: true
          schema:
            type: number
            minimum: 1
            maximum: 500
          example: "78"
      responses:
        '204':
          description: Успешный запрос без содержимого
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Ресурс не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
 
  /organization/create:
    post:
      tags: 
        - Работа с организациями
      summary: Создать организацию
      operationId: createOrg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationName:
                  type: string
                  pattern: ^[A-Za-zА-Яа-яЁё]+$
                  minLength: 1
                  maxLength: 255
                  description: Наименование организации
                  example: "ПАО СБЕРБАНК"
                inn:
                  type: number
                  minLength: 10
                  maxLength: 12
                  description: ИНН организации
                  example: 7707083893
                kpp:
                  type: number
                  minLength: 9
                  maxLength: 9
                  description: КПП организации
                  example: 773601001  
                dateCreate:
                  type: string
                  format: date-time
                  description: Дата и время создания карточки с часовым поясом
                  example: "2025-12-01T18:00:00-05:00"

      responses:
        '201':
          description: Организация успешно создана
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationId:
                    type: number
                    minimum: 1
                    maximum: 500
                    description: Уникальный идентификатор организации
                    example: 177
                  message:
                    type: string
                    description: Сообщение об успешном создании
                    example: "Organization created successfully"
                example:
                  id: "177"
                  message: "Organization created successfully"
        '204':
          description: Успешный запрос без содержимого
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Конфликт (например, дубликат)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Ошибка бизнес-логики
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /organization/change:
    put:
      tags: 
        - Работа с организациями
      summary: Изменить информацию об организации
      operationId: updateOrgInfo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                inn:
                    type: number
                    minLength: 10
                    maxLength: 12
                    description: ИНН организации
                    example: 7707083893
                kpp:
                    type: number
                    minLength: 9
                    maxLength: 9
                    description: КПП организации
                    example: 773601001
                organizationName:
                    type: string
                    pattern: ^[A-Za-zА-Яа-яЁё]+$
                    minLength: 5
                    maxLength: 255
                    description: Наименование организации
                    example: "ПАО СБЕРБАНК"
                numberOfEmployees:
                    type: number
                    description: Количество сотрудников
                    minimum: 1
                    example: 1000
                isActive:
                    type: boolean
                    description: Активна ли организация
                    example: true
                products:
                    type: array
                    description: Список продуктов
                    maxItems: 10
                    items:
                      type: object
                      properties:
                        productId:
                          type: number
                          description: Идентификатор продукта
                          example: 50085
                          minimum: 5
                        productName:
                          type: string
                          description: Название продукта
                          pattern: ^[A-Za-zА-Яа-яЁё]+$
                          example: "Продукт 1"                
 
      responses:
        '200':
          description: Организация успешно обновлена
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  message:
                    type: string
                example:
                  id: "10009"
                  message: "Организация успешно обновлена"
        '204':
          description: Успешный запрос без содержимого
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Конфликт (например, дубликат)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Ошибка бизнес-логики
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error_code:
          type: string
          description: Код ошибки
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Описание ошибки
          example: "Ошибка валидации данных"
        details:
          type: array
          description: Подробности ошибки
          maxItems: 100
          items:
            type: object
            properties:
              field:
                type: string
                description: Поле, где произошла ошибка
                example: "company_id"
              issue:
                type: string
                description: Проблема с полем
                example: "Обязательное поле"
              resolution:
                type: string
                description: Рекомендация по исправлению
                example: "Укажите корректный идентификатор"
        request_id:
          type: string
          description: Идентификатор запроса для отладки
          example: "req_123456"
    getOrganizationInfo:
      type: object
      required:
        - inn
        - kpp
        - organizationName
        - numberOfEmployees
        - isActive
      properties:
        inn:
          type: number
          description: ИНН организации
          minLength: 10
          maxLength: 12
          example: "7707083893"
        kpp:
          type: number
          description: КПП организации
          minLength: 9
          maxLength: 9
          example: "773601001"
        organizationName:
          type: string
          description: Название организации
          pattern: ^[A-Za-zА-Яа-яЁё]+$
          maxLength: 255
          example: "ПАО СБЕРБАНК"
        numberOfEmployees:
          type: number
          description: Количество сотрудников
          minimum: 1
          example: 100
        isActive:
          type: boolean
          description: Активна ли организация
          example: true
        products:
          type: array
          description: Список продуктов
          maxItems: 10
          items:
            type: object
            properties:
              productId:
                type: number
                description: Идентификатор продукта
                minimum: 5
                maximum: 999999
                example: 50085
              productName:
                type: string
                description: Название продукта
                maxLength: 255
                pattern: ^[A-Za-zА-Яа-яЁё]+$
                example: "Продукт 1"