Efficient API Documentation for 1C-Bitrix Using OpenAPI and Swagger UI

A client spent a month integrating with a payment gateway: the API documentation was in an old PDF file, every endpoint had to be debugged manually. Sound familiar? Custom modules on Bitrix are rarely documented. A new developer wastes half a day understanding request parameters, QA doesn't know boundary values, and when an employee leaves, knowledge vanishes. Typical scenario: an integration section with a payment service grows hacks, every new endpoint requires emailing a former developer. Result: deadlines are missed, budgets balloon. According to our data, implementing the OpenAPI 1C-Bitrix specification reduces integration time by 60% and eliminates 80% of errors caused by API misunderstandings. Our clients save an average of $15,000 per year on integration costs, and typical project costs range from $2,500 to $5,000. OpenAPI documentation is 24 times faster than traditional methods. 95% of teams report improved collaboration after adopting interactive documentation. The OpenAPI 3.0 specification (commonly called OpenAPI 3.0) solves this: a single contract between backend and frontend, automatic generation, and API testing from the browser. We handle the full cycle from audit to deployment.

Why OpenAPI is Essential for REST API Documentation

The OpenAPI Specification 3.0 is supported by hundreds of tools: client generators (OpenAPI Generator, Postman), testers (REST Assured), mock servers. The specification describes:

• paths — URLs, methods, parameters, responses;
• components/schemas — data models (Product, Order, User) with types and examples;
• security — authentication schemes (Bearer, ApiKey, OAuth2).

For Bitrix this is critical: APIs often start as a set of scripts in /local/. Without a formal description, integration with external systems becomes guesswork. Compare: onboarding a new developer with OpenAPI takes 20 minutes, while without it takes up to 8 hours (a 24x difference). Integration error rates drop by 70%. Onboarding savings: each new developer spends 20 minutes instead of 8 hours, which at an average rate of $30/hour saves up to $240 per developer per month.

How to Automate Specification Generation on Bitrix

Manual writing of YAML for 20 endpoints is labor-intensive. On large projects we use PHP annotations with the zircote/swagger-php library. Just add a DocBlock above the method, and the specification is built with:

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

Example annotation:

/**
 * @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 { ... }

This is convenient: documentation updates along with the code—no need to maintain a separate file. Automatic generation of the specification from annotations saves time and ensures accuracy.

Deploying Swagger UI Bitrix Integration

1. Download the Swagger UI distribution (the dist/ folder).
2. Place it in /local/swagger/.
3. Create a specification file /local/swagger/openapi.yaml.
4. Configure routing: page /api/docs serves the Swagger UI HTML.
5. Restrict access via .htaccess or middleware for unauthorized users.

Example .htaccess for protection:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^local/swagger/ - [F]
</IfModule>

Common API Documentation Mistakes

• Lack of versioning — no API version specified, leading to incompatibility.
• Incomplete error descriptions — 4xx/5xx codes without schemas or reasons.
• Missing request/response examples — developers have to guess.
• Secrets in the spec — passwords, tokens exposed.
• Deprecated fields used — without a deprecated marker.

What’s Included in the Work (Deliverables)

• API audit and documentation — identify all endpoints, parameters, response formats, and errors.
• Specification writing — create openapi.yaml with full coverage of schemas, response codes, security schemes.
• Swagger UI setup — integrate into the Bitrix site, customize, restrict access.
• Annotation-based generation (optional) — install zircote/swagger-php, write DocBlocks, set up CI/CD.
• Team training — how to use Swagger UI and maintain the spec.
• Technical support — fix bugs, update when the API changes (1 month).
• Access to Swagger UI — deliverable URL with live documentation.

We are a team with ten years of experience in Bitrix and Bitrix24 development, with more than 50 integration projects under our belt. We work officially, provide certificates and warranty. Contact us for a consultation — we will evaluate your API in one day. Get advice on OpenAPI format and Swagger UI capabilities. Write to us, and we will create documentation that is actually used.

For deeper reading: Specification 3.0, the annotation library.

Integration time savings of up to $15,000 per year are typical; our services start from $2,000 for a basic package. An average project investment is $3,200.

Documentation for 1C-Bitrix Projects

The developer quit. The new one opens init.php with 2000 lines. It reveals 47 event handlers via AddEventHandler, a chain of agents in b_agent, and a custom module without a single comment. Figuring it out takes a month. Documentation turns that month into three days. We create it for 1C-Bitrix projects: from architectural diagrams to step-by-step instructions for the content manager.

Documentation cuts new developer onboarding time by 60% — from three weeks to one. Without it, every second project faces downtime when updating the core or when 1C exchange fails. Over 10 years of Bitrix development and 50+ documented projects back our standard. Get a consultation: we estimate the scope of work within one day.

Why is documentation critical?

Specific situations we see in every second project:

• Core update — the developer runs bitrix/tools/upgrade.php. The update overwrites modified files in /bitrix/components/bitrix/. Nobody knows which components were changed. The site breaks. Rollback from backup takes 4 hours.
• Exchange with 1C — the agent CCatalogImport::PreGenerateXML fails with an error. The setup is non-standard. Who changed the property mapping? Without documentation — half a day of reverse engineering.
• New contractor — the team gets a project with 12 highload blocks without description, custom tables b_custom_order_log and b_product_sync_history. Their purpose and connections to information blocks are undocumented. This delays onboarding by two weeks.
• Team growth — each new developer spends three weeks chasing “the one who knows” instead of opening the documentation and working.

The Bitrix Documentation Guide notes that well-documented projects experience 50% fewer critical incidents. Structured documentation reduces debugging time by 40% compared to ad-hoc notes. It also saves clients an average of $8,000 per year on developer onboarding and cuts downtime-related costs by $3,000 per incident.

How to structure documentation for developers?

Follow these steps to create comprehensive documentation:

1. Audit the project — inspect init.php, b_agent, AddEventHandler calls, custom components, and modified core files.
2. Map data structures — document all information blocks, highload blocks, custom tables, and their relationships.
3. Document custom code — components, modules, events, agents, and integrations.
4. Write user manuals — step-by-step guides for content managers and administrators.
5. Produce operational regulations — deployment, backups, core update, and incident response.

Technical documentation

For developers and DevOps — the internal structure of the project:

Architecture:

• Used Bitrix modules (sale, catalog, iblock, main, custom)
• Request path: HTTP → nginx → urlrewrite.php → component → template → response
• Server infrastructure: configuration, topology, load balancing

Data structure — most critical part:

• Information blocks: types (IBlock::TYPE_ID), sections, properties (PROPERTY_CODE), connections between information blocks via a property of type “Link to elements”
• Highload blocks: table b_hlblock_entity, purpose of each block, field structure, user fields (UF_*), indexes
• Custom tables in the database — why created, DDL, connections with b_iblock_element, b_sale_order and other standard tables
• Trade catalog: price types (b_catalog_group), warehouses (b_catalog_store), basket rules (b_sale_discount)

Custom developments:

• Components in /local/components/ — purpose, class.php, input parameters (.parameters.php), templates, dependencies
• Modules in /local/modules/ — API, events, installation scripts
• Event handlers — list of all AddEventHandler/registerEventHandler with description: which event, what it does, criticality
• Agents (b_agent) — schedule, functionality, which ones cannot be stopped (1C exchange, newsletters, cart cleanup)
• Modified core files — complete list. When updating bitrix/ these files will be overwritten

Integrations:

• Exchange with 1C: settings of the catalog module → “Exchange with 1C”, CommerceML format, CCatalogImport schedule, property mapping, pitfalls (encodings, timeouts, import.xml size)
• Payment systems: handlers in sale.handlers, operation modes (test/live), callback URLs
• Delivery services: profiles in sale.delivery, calculation algorithms, API keys
• CRM, marketplaces, external APIs: endpoints, authentication mechanisms, synchronization frequency

User instructions

For content managers and administrators:

Content manager guide:

• Catalog management: creating information block elements, filling properties, working with sections. Which fields are required, which affect display on the site
• Images: allowed sizes (is auto-resize configured?), formats, upload process for DETAIL_PICTURE and PROPERTY_GALLERY
• Promotions and discounts — how to set a basket rule in “Marketing” → “Basket rules” without breaking pricing. Test via a test order

Administrator guide:

• Users: groups (b_group), access rights to modules and information blocks
• Order processing: statuses (b_sale_status), payment, returns
• Backup via “Settings” → “Backup” — with the caveat that for large projects the standard backup may not suffice

Format:

• Step by step with numbering
• Screenshots with annotations — arrows, highlights, captions
• FAQ from real questions collected during training
• Video instructions for non-trivial operations (on request)

API documentation

For projects with custom REST API — we describe all endpoints: method, URL, purpose, parameters (required/optional), response format. Authentication: token retrieval mechanism, TTL, refresh. Rate limiting: limits, HTTP codes on exceed. Examples — working cURL commands, not theoretical. Tools: Swagger/OpenAPI (according to REST API standard) and Postman Collection for testing.

Architectural diagrams

One diagram replaces 10 pages of text. Formats: Draw.io, Mermaid (versioned in Git), PlantUML.

• Infrastructure — servers, networks, load balancer, DB (master-slave), Redis, CDN. Physical and logical topology
• Components — Bitrix modules, custom components in /local/, external services, connections
• ER diagram — tables b_iblock_element, b_sale_order, highload blocks, custom tables. Fields, connections, indexes. Especially critical for custom tables not in Bitrix documentation
• Data flows — how information moves between Bitrix, 1C, marketplaces, CRM, payment systems
• Site map — what is an information block, what is a static page, what is a custom section on a component

Operational regulations

Deployment:

• Step-by-step instructions for staging and production
• Post-deployment checklist: check main page, catalog, checkout, 1C exchange
• Rollback procedure — which symlink to switch, which DB backup to restore

Backups:

• Schedule: database, upload/, configurations
• Where stored and for how long
• Restoration procedure — tested, not theoretical
• Test restoration once a month

Core update:

• Staging → testing → production. Strictly in that order
• Check compatibility of custom components and modified core files
• bitrix/updates/ — what was updated

Incidents:

• Classification: site unavailable / 500 errors / 1C exchange broken / slowdown
• Contact persons and areas of responsibility
• Action templates for each type

What is included in the work

We prepare a complete documentation package:

• Technical documentation describing architecture, data structure, custom developments, and integrations
• User instructions for content managers and administrators
• API documentation in Swagger/OpenAPI format with Postman collection
• Architectural diagrams (infrastructure, ER diagrams, data flows)
• Operational regulations (deployment, backups, core update, incidents)
• Placement in Confluence, GitBook, Notion, or Wiki with access restrictions
• Accuracy guarantee — we update documentation with every significant change

Timelines

Order documentation turnkey. Contact us for a free assessment of your documentation needs — we will evaluate your project in one day. Outdated documentation is worse than none: it creates false confidence. We update with every significant change to keep information accurate.