REST API Documentation

include::docs/openapi.yaml[]

# API Recommendation Service

```yaml
openapi: 3.0.1
info:
  title: Bank Recommendation Service API
  version: 1.0.0
  description: |
    API для системы рекомендации банковских продуктов.
    Позволяет управлять правилами и получать персональные рекомендации.

servers:
  - url: https://api.bank-star.com/v1
    description: Production

paths:
  /recommendation/{user_id}:
    get:
      tags: [Recommendations]
      summary: Get recommendations for user
      parameters:
        - in: path
          name: user_id
          required: true
          schema: { type: string, format: uuid }
          example: "d4a4d619-9a0c-4fc5-b0cb-76c49409546b" 
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationResponse'
        '404':
          description: User not found

  /rule:
    post:
      tags: [Rules] 
      summary: Create new dynamic rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRuleRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleResponse'

components:
  schemas:
    RecommendationResponse:
      type: object
      properties:
        user_id: { type: string, format: uuid }
        recommendations: 
          type: array
          items: { $ref: '#/components/schemas/RecommendationItem' }
      example:
        user_id: "d4a4d619-9a0c-4fc5-b0cb-76c49409546b"
        recommendations:
          - name: "Top Saving"
            id: "59efc529-2fff-41af-baff-90ccd7402925"
            text: "Описание продукта..."

    CreateRuleRequest:
      type: object
      required: [product_name, product_id, rule]
      properties:
        product_name: { type: string }
        product_id: { type: string, format: uuid }
        rule:
          type: array
          items: { $ref: '#/components/schemas/RuleCondition' }

Как использовать

1. Получение рекомендаций

Запрос:

GET /recommendation/d4a4d619-9a0c-4fc5-b0cb-76c49409546b

Ответ:

{
  "user_id": "d4a4d619-9a0c-4fc5-b0cb-76c49409546b",
  "recommendations": [
    {
      "name": "Invest 500",
      "id": "147f6a0f-3b91-413b-ab99-87f081d60d5a",
      "text": "Описание продукта..."
    }
  ]
}

2. Создание правила

Запрос:

POST /rule
Content-Type: application/json

{
  "product_name": "Простой кредит",
  "product_id": "ab138afb-f3ba-4a93-b74f-0fcee86d447f",
  "rule": [
    {
      "query": "USER_OF",
      "arguments": ["CREDIT"],
      "negate": true
    }
  ]
}

3. Статистика

GET /rule/stats

Визуализация

Для просмотра в Swagger:

1. Откройте /swagger-ui.html
2. Или импортируйте YAML в Swagger Editor