OpenAPI for 1C-Bitrix: why integrations break at the junction
The API has methods, but their descriptions live separately from the code: a change was made to the handler, the specification was left untouched.
The external team reads such documentation as the source of truth, builds the integration against outdated fields — and hits a failure already in production, when data doesn't arrive or arrives in the wrong form. The cost is not only a broken scenario, but also hours spent figuring out whose side is to blame.
A familiar picture: a method's set of required parameters changed, a new response type was added, or an error code changed — while the description still holds the previous contract.
The developer on the other side plugs in the old values, gets an unclear error, and goes off to sort out the relationship. Then come the correspondence, the calls, the manual request runs — all of it instead of working on the task. The more external consumers an API has, the more expensive each such desynchronization becomes.
The root cause is that the contract isn't described formally. As long as methods are documented in text in a wiki or in code comments, the integration has no single source of truth.
OpenAPI for 1C-Bitrix closes exactly this gap: the API method description becomes a machine-readable specification, from which clients are generated, requests and responses are validated, and discrepancies become visible before rollout rather than after.
Next, we break down how to build such a description so that integration with Bitrix stops being a lottery and integration errors are caught at the build stage rather than in the heat of battle.
What changes after describing an API according to a specification
When an API contract is fixed in a specification, the external team stops trying to figure out the field format through back-and-forth messages and reads it themselves.
In practice, integration onboarding time is reduced from weeks of coordination to one or two days: a developer opens the description, generates a client for their language, and immediately sees the required parameters, types, and response structure. Request errors are caught at build time, not in production.
The load on support drops predictably: typical questions like "which field is required," "what will come back in an error response," "how do I pass a date" stop reaching your team, because the answer is in the specification.
Based on our experience, the share of such requests drops by several times — engineers focus on development rather than explaining formats.
A separate effect is that an entire class of failures due to incorrect fields disappears. When the schema is validated on input and output, a type mismatch or a missing required parameter returns a clear error instead of corrupting data in the system.
Data consistency between services rests on a single source of truth: the specification is updated together with the code, and both sides see the current version of the contract rather than diverging agreements.
Finally, support gets a foundation for changes. Before making modifications, it is clear which fields are already used by external systems and which can be changed without risk.
Backward compatibility is checked against the specification rather than the developer's memory, so releases do not unexpectedly break other teams' integrations.
Ways to Describe an API: Manual Specification, Generation, Hybrid
An API specification lives exactly as long as it matches the code.
As soon as the contract diverges from the implementation, integrations for external teams break, and support turns into figuring out "why the documentation says one thing but the response says another." So choosing a description method is not a choice of file format, but a choice of how much effort will go into keeping it up to date.
| Approach | When it fits | Limitations |
|---|---|---|
| Manual specification | A small public contract, stable methods, external partners | Diverges from the code with every refactoring, manual edits, easy to forget about a new parameter |
| Generation from code | Internal services with frequent releases, a single stack | Describes only what is marked up with annotations, drags along the class structure, noisy service fields |
| Hybrid approach | A public contract + active development | Requires agreement on who owns the schema, and checks in the build |
Where the boundary lies
Manual description is justified when the contract is narrow and rarely changes: a few methods for an external system, where wording and examples matter more than completeness.
Here the engineer deliberately writes the schema and keeps it as a separate artifact — but is obliged to build in a reconciliation with the code, otherwise after a couple of releases the description will start lying.
Generation from code wins where there are dozens of methods and they change every week: the schema is assembled from markup in the controllers, makes its way into the build, and is updated along with the release.
Up-to-dateness is maintained automatically, but the quality of the description is limited to what is marked up — readability suffers without manual polishing.
The hybrid in real work
In practice, we more often assemble a combined mode: the skeleton and models are generated from the code, while descriptions, request and response examples, and error codes are written in manually on top.
This way up-to-dateness is ensured by generation, and the labor intensity of maintenance drops — it's the text that gets edited, not the structure.
We build the check into the build: if the schema diverges from the implementation, the build fails before the release, not after a complaint from the integrator.
How we implement API description: stages of work
We start with an inventory of methods: we collect all entry points — REST controllers of modules, webhooks, exchanges with external systems, and calls that have historically "taken root" in integrations.
The output is a list of endpoints indicating who calls them and what will break if the contract changes. Without this step, the description quickly diverges from reality and loses value for the team.
Next, we describe the data schema: field types, requiredness, date formats, response and error codes.
We assemble the schema from the code, not from the developers' memory — this way, discrepancies between the documentation and the service's behavior surface at the description stage, not in production.
- Inventory of methods — we record all entry points, their owners, and consumers.
- Data schema — we describe models, fields, response and error codes in a unified format.
- Specification assembly — we consolidate the methods into a single description file and link the models with references.
- Verification on a test environment — we run requests against the specification and compare the actual responses with the described ones.
- Setting up interactive documentation — we deploy a page where each method can be called directly from the browser.
- Update policy — we establish the rule: a contract change without an update to the description does not pass review.
- Handover of the description — we provide the client's team with access credentials, the file structure, and maintenance instructions.
What this order provides
Verification on a test environment is the key step: it catches methods that formally work but return something other than what is declared in the schema. After it, the specification becomes the source of truth that both the frontend and external integrators rely on.
The update policy addresses the main reason descriptions die: edits in the code without a synchronized change to the specification. We embed the check into the build process — the discrepancy is visible before release, not six months later in correspondence with a partner.
What the client receives
We hand over not a "file describing methods" but a working documentation loop that an external team or your integrator can use to connect to the system without going back and forth with the developers.
- API specification — a single document in OpenAPI format describing all methods, data schemas, response and error codes. This is the source of truth: both the documentation and the client libraries are generated from it, so any discrepancy between the code and the description becomes visible immediately rather than at the integration stage.
- Interactive documentation — a full Swagger UI on your domain where a method can be called right from the page: plug in a token, send a request, and see the real response. An engineer can verify how the system behaves before writing the first line of code.
- Request examples — ready-made snippets in the languages your team uses, with authorization, pagination, and error handling. This eliminates the most common class of support requests.
- Versioning rules — a fixed scheme: how a new version is released, how long the old one lives, how far in advance we announce changes, and what counts as a breaking change. Updates stop being a surprise for those who have already integrated.
- Support policy — who answers API questions and within what timeframes, how requests for new methods are filed, and where incident notifications are sent.
- Access scheme — where keys are issued, what permission scopes exist, and how access is revoked when an employee leaves.
- Documentation update procedure — the rule that a code change cannot make it into a release without a specification update.
Every artifact stays alive: the specification lives next to the code, is updated in the same release, and undergoes automatic compliance checks. Describe your system — we will come back with a scope estimate and a work plan.
Case study: describing the API of an online store on 1С-Bitrix
An online store on 1С-Bitrix with its own storefront and exchange with an accounting system. Partners connected to the store — marketplaces, delivery services, external loyalty services.
Each connection went through correspondence: the partner sent questions, the developer replied with code fragments, and the integration stretched over weeks.
What it was before
There was no single API description. The partner got access to the methods and figured out the request structure on their own: which fields are required, in what date format, what would be returned for a partial order.
Errors surfaced in production — the integration crashed on an incorrectly passed status or an empty address field, and troubleshooting took more time than the fix itself.
What was changed
We assembled an OpenAPI specification for all public methods: requests, responses, error codes, required and optional fields, examples for each scenario.
We set up Swagger UI — the partner opens the page, sees the methods, fills in values, and checks the response right in the interface, without server access and without correspondence with our team.
The specification was tied to the repository: if a method changes, the description is updated in the same commit.
What it became
The average partner onboarding time dropped from three weeks to a few days — most questions are resolved by the interactive documentation.
The class of failures due to incorrect fields is gone: the partner sees the format before the first request is sent, not after the exchange crashes.
The load on support decreased — typical inquiries about request structure have practically stopped, and the freed-up time went into developing integrations.
How OpenAPI differs from Swagger UI and which to choose
OpenAPI is a specification, that is, a format for describing an API: a file in YAML or JSON that records endpoints, methods, request and response schemas, error codes, and authorization rules.
By itself, it doesn't render anything or run anything — it's a contract that the backend, frontend, and external integrators agree on.
The specification can be validated in CI, client libraries and server stubs can be generated from it, and versions can be compared between releases.
Swagger UI is a visualization tool: it reads a ready-made OpenAPI file and turns it into an interactive page with a tree of methods, examples, and a "execute request" button.
The confusion arises from history: the format used to be called Swagger, later it was renamed to OpenAPI, and the name Swagger remained with the family of utilities around it.
That's why "do Swagger" is a meaningless phrasing: it's unclear whether we're writing a description or just wiring up a documentation page.
For setting a task, the difference is fundamental. If you need a single source of truth for integrations and code generation, you work with the OpenAPI specification.
If you need a page where a contractor or partner manually checks methods, that's a Swagger UI layer on top of an already existing description. One doesn't work without the other: without a correct specification, the visualization will show an empty or incorrect picture.
In practice, we cover both parts: we describe the contract in OpenAPI, wire up Swagger UI for manual checks, and set up automatic verification of the specification against the code so that the documentation doesn't diverge from the actual API behavior after every release.
Common technical concerns about API description
Concerns about API description usually arise not at the start, but at the stage when the specification has already been written and needs to be kept alive.
Below is an analysis of the situations we encounter most often: deprecated methods, closed environments, versioning, and maintaining the description after launch.
What should be done with methods that are already deprecated but are still being called by clients?
We do not remove them from the description, but mark them as deprecated, indicating the replacement method and the retirement timeline.
In the specification, such a method remains visible, but is flagged in the interface — integrators immediately see that they need to migrate and do not build new logic on a dead-end branch. Removing it without a transition period breaks scenarios that are already in operation.
Can the description interface be deployed within the customer's closed environment?
Yes. The specification and interface are deployed on your infrastructure, without accessing external services — this matters when the documentation describes internal methods.
Access is restricted using the same mechanisms as for other internal services: authorization, roles, and request logging.
How should API versions be described so that old integrations do not break?
Each version is fixed with its own description, and changes within a version are divided into compatible and breaking. Breaking changes go only into a new version, while the old one continues to work and remains in the specification.
This way, the integrator sees which version they are tied to and plans the transition without a rush.
Who maintains the description after launch, and how is this organized?
The description lives in the same repository as the code and is updated as part of regular tasks. When a method changes, the specification is edited, and a divergence check runs automatically.
If the description diverges from the implementation, the build signals this before deployment, not after an integrator's complaint.
Does a public description reveal too much about the internal system?
Only what is needed for integration is published: methods, parameters, and response formats. Internal addresses, service fields, and infrastructure details do not go into the specification. We determine the visibility boundary together with your team before publication.
If you still have questions about your system that are not on the list, describe the task, and we will get back to you with an estimate and a work plan.
Let's discuss your 1C-Bitrix API documentation task
To make the API documentation useful rather than a formality, we start by breaking down the task: which integrations are already running, who calls them and how, and what's preventing a new consumer from connecting.
Then we define the boundaries of the landscape — where the services live, how access is set up, and whether there are external systems outside the perimeter. This determines both the specification format and the scope of work.
Describe what you already have and what you need to achieve — we'll come back with an estimate and an API documentation plan.
- Which methods and entities need to be documented first
- A list of existing integrations: internal services, external contractors, mobile clients
- Landscape constraints: network zones, access, security requirements
- Current state: whether there are draft schemas, code comments, outdated instructions
- Target scenario: who will read the specification and what they should be able to do based on it
- Environment requirements: where the documentation should be available and how often it should be updated
- Expected result: an interactive specification, request examples, a support policy
Based on the conversation, we'll propose a documentation structure, estimate the effort, and give you timelines. If some integrations are still in development, we'll factor them into the plan so the specification doesn't become outdated by launch time.