Developing Swagger/OpenAPI documentation for the 1C-Bitrix API

Swagger/OpenAPI Documentation Development for 1C-Bitrix API

Swagger (OpenAPI Specification) is a standard format for describing REST APIs. From the specification, interactive documentation is automatically generated: developer sees all endpoints, parameters, request and response formats, can make a test request right from the browser.

Why document Bitrix API

The standard Bitrix24 REST API is documented on the developer portal. But this is about API you developed: custom endpoints, own modules, integration solutions. Without documentation:

• Integration developer spends hours figuring out request format.
• QA doesn't know what and how to test.
• Team rotation loses knowledge.

OpenAPI solves this: specification is simultaneously documentation, contract and testing tool.

OpenAPI 3.0 format: basic structure

openapi: 3.0.3
info:
  title: My Bitrix API
  version: 1.0.0
  description: Custom 1C-Bitrix API for working with catalog

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

paths:
  /products:
    get:
      summary: Product list
      parameters:
        - name: category_id
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '401':
          $ref: '#/components/responses/Unauthorized'

Placing documentation on Bitrix

Swagger UI is a static web application that renders OpenAPI specification into an interactive interface. Placement on Bitrix site:

1. Download Swagger UI: dist/ folder from GitHub or via npm.
2. Place in /local/swagger/.
3. Create file /local/swagger/openapi.yaml or openapi.json with specification.
4. Configure routing: /api/docs → serves HTML Swagger UI, which loads openapi.yaml.
5. Close access to /api/docs for unauthorized users via .htaccess or middleware.

File openapi.yaml can be generated dynamically — PHP script collects descriptions of all registered endpoints and returns JSON/YAML. Convenient if API structure changes often.

Authorization description

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

security:
  - BearerAuth: []

In Swagger UI, "Authorize" buttons appear — developer enters token once, and all requests from interface are sent with Authorization: Bearer {token} header.

Data schemas (components/schemas)

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

Schemas are reused via $ref — describe structure once, use in all endpoints.

Generating specification from annotations (zircote/swagger-php)

For large APIs it's more convenient to describe endpoints in annotations right in code:

/**
 * @OA\Get(
 *     path="/products/{id}",
 *     summary="Get product by ID",
 *     @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
 *     @OA\Response(response=200, description="Product found",
 *         @OA\JsonContent(ref="#/components/schemas/Product")
 *     )
 * )
 */
public function getProduct(int $id): array { ... }

Library zircote/swagger-php scans folders with annotations and generates openapi.json:

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

Documentation automatically updates with code.

Developing documentation for API with 10-20 endpoints — 2-3 days including Swagger UI setup and data schema description.