API Documentation: автогенерация из Mock API [Always Up-to-Date]

# openapi.yaml
openapi: 3.0.0
info:
  title: Users API
  description: API для управления пользователями
  version: 1.0.0
  contact:
    name: API Support
    email: api@company.com

servers:
  - url: https://api.company.com/v1
    description: Production
  - url: https://staging-api.company.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: Получить список пользователей
      description: Возвращает пагинированный список всех пользователей
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: Номер страницы (начиная с 1)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Количество пользователей на странице
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: role
          in: query
          description: Фильтр по роли
          required: false
          schema:
            type: string
            enum: [admin, user, guest]
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 150
                      page:
                        type: integer
                        example: 1
                      limit:
                        type: integer
                        example: 20
        '400':
          description: Неверные параметры запроса
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      summary: Создать нового пользователя
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
              properties:
                name:
                  type: string
                  minLength: 2
                  maxLength: 100
                  example: "Иван Иванов"
                email:
                  type: string
                  format: email
                  example: "ivan@example.com"
                role:
                  type: string
                  enum: [admin, user, guest]
                  default: user
      responses:
        '201':
          description: Пользователь успешно создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Ошибка валидации
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '409':
          description: Email уже занят
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{id}:
    get:
      summary: Получить пользователя по ID
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: ID пользователя
          schema:
            type: integer
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Пользователь не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Иван Иванов"
        email:
          type: string
          format: email
          example: "ivan@example.com"
        role:
          type: string
          enum: [admin, user, guest]
          example: "user"
        createdAt:
          type: string
          format: date-time
          example: "2026-01-27T10:00:00Z"
        updatedAt:
          type: string
          format: date-time
          example: "2026-01-27T10:00:00Z"

    Error:
      type: object
      properties:
        error:
          type: string
          example: "Internal Server Error"
        message:
          type: string
          example: "Произошла ошибка при обработке запроса"

    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: "Validation Error"
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email: ["Email обязателен", "Email должен быть валидным"]
            name: ["Имя должно быть не менее 2 символов"]

# Способ 1: Через Web UI (2 минуты)
# 1. Зарегистрируйтесь на lightboxapi.ru
# 2. Создайте workspace
# 3. Import → Upload openapi.yaml
# 4. Получите URLs:
#    - Mock API: https://your-team.lightboxapi.com
#    - Docs: https://your-team.lightboxapi.com/docs

# Способ 2: Через API
curl -X POST https://api.lightboxapi.com/v1/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@openapi.yaml" \
  -F "workspace=your-team"

# Response:
# {
#   "mockApiUrl": "https://your-team.lightboxapi.com",
#   "docsUrl": "https://your-team.lightboxapi.com/docs",
#   "endpoints": 3,
#   "status": "ready"
# }

# .github/workflows/update-docs.yml
name: Update API Documentation

on:
  push:
    branches: [main]
    paths:
      - 'openapi.yaml'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Upload OpenAPI to LightBox API
        run: |
          curl -X POST https://api.lightboxapi.com/v1/import \
            -H "Authorization: Bearer ${ secrets.LIGHTBOX_API_KEY }" \
            -F "file=@openapi.yaml" \
            -F "workspace=your-team"

      - name: Notify team
        run: |
          curl -X POST ${ secrets.SLACK_WEBHOOK } \
            -H 'Content-Type: application/json' \
            -d '{
              "text": "✅ API Documentation обновлена: https://your-team.lightboxapi.com/docs"
            }'