Розробка Swagger/OpenAPI документації для API 1С-Бітрікс

Розробка документації Swagger/OpenAPI для API 1С-Bitrix

Swagger (OpenAPI Specification) — це стандартний формат описання REST API. Із специфікації автоматично генерується інтерактивна документація: розробник бачить усі ендпоінти, параметри, формати запитів та ответів, може зробити тестовий запит прямо з браузера.

Навіщо документувати API Bitrix

Стандартне REST API Bitrix24 задокументовано на порталі розробників. Але мова йде про API, розроблений вами: кастомні ендпоінти, власні модулі, інтеграційні рішення. Без документації:

• Розробник-інтегратор тратить години на вивчення формату запитів.
• Тестувальник не знає, що та як перевіряти.
• При ротації команди знання втрачаються.

OpenAPI вирішує цю проблему: специфікація — це водночас документація, контракт та інструмент тестування.

Формат OpenAPI 3.0: базова структура

openapi: 3.0.3
info:
  title: My Bitrix API
  version: 1.0.0
  description: Кастомний API 1С-Bitrix для роботи з каталогом

servers:
  - url: https://mysite.ru/api/v1
    description: Production

paths:
  /products:
    get:
      summary: Список товарів
      parameters:
        - name: category_id
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Успішна відповідь
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '401':
          $ref: '#/components/responses/Unauthorized'

Розташування документації на Bitrix

Swagger UI — це статичне веб-приложення, яке рендерить OpenAPI-специфікацію в інтерактивний інтерфейс. Розташування на сайті Bitrix:

1. Завантажити Swagger UI: папку dist/ з GitHub або через npm.
2. Розмістити в /local/swagger/.
3. Створити файл /local/swagger/openapi.yaml або openapi.json зі специфікацією.
4. Налаштувати роутинг: /api/docs → відправляє HTML Swagger UI, який завантажує openapi.yaml.
5. Закрити доступ до /api/docs для неавторизованих користувачів через .htaccess або middleware.

Файл openapi.yaml можна генерувати динамічно — PHP-скрипт збирає описи всіх зареєстрованих ендпоінтів та відправляє JSON/YAML. Це зручно, якщо структура API змінюється часто.

Опис авторизації

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - BearerAuth: []

У Swagger UI з'являються кнопки «Authorize» — розробник вводить токен один раз, і всі запити з інтерфейсу йдуть з заголовком Authorization: Bearer {token}.

Схеми даних (components/schemas)

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          example: 1234
        name:
          type: string
          example: "Ноутбук Dell XPS 15"
        price:
          type: number
          format: float
          example: 89990.00
        currency:
          type: string
          enum: [RUB, USD, EUR]
        in_stock:
          type: boolean
      required:
        - id
        - name
        - price

Схеми переиспользуються через $ref — описуєте структуру один раз, використовуєте у всіх ендпоінтах.

Генерація специфікації з аннотацій (zircote/swagger-php)

Для великих API зручніше описувати ендпоінти в аннотаціях прямо в коді:

/**
 * @OA\Get(
 *     path="/products/{id}",
 *     summary="Отримати товар за ID",
 *     @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
 *     @OA\Response(response=200, description="Товар знайдено",
 *         @OA\JsonContent(ref="#/components/schemas/Product")
 *     )
 * )
 */
public function getProduct(int $id): array { ... }

Бібліотека zircote/swagger-php сканує папки з аннотаціями та генерує openapi.json:

composer require zircote/swagger-php
./vendor/bin/openapi /local/api --output /local/swagger/openapi.json

Документація автоматично оновлюється разом з кодом.

Розробка документації для API з 10-20 ендпоінтів — 2-3 дні з урахуванням налаштування Swagger UI та описування схем даних.