OpenAPI specs maintenance

OpenAPI specs maintenance is the creation and keeping up to date of the OpenAPI specification of your API: a formal, machine-readable description of all methods, parameters, responses and errors. The specification is the source of truth for everything around the API: documentation (see the “Developer documentation” service), client SDKs (see the “SDK generation” service), an interactive playground (see the “API playgrounds” service) and Postman collections (see the “Postman collections maintenance” service) are all generated from it. So its quality determines the quality of everything else: an accurate spec means the docs, the SDK and the sandbox are built from it already correct; an inaccurate one propagates the same error into every artifact at once. An honest caveat: automatic generation carries into the artifacts exactly what is in the spec — it does not fix the spec for you, so the quality of everything still equals the quality of the spec and the process of maintaining it. We put your specification in order (or create it from scratch from the real API), bring it up to the OpenAPI 3.x standard, set up linting and checks, and most importantly link it to the code so the spec does not drift from reality: contract tests and CI checks catch discrepancies before an integrator sees them. Importantly and honestly: the value of a specification is that it matches the real API. A spec that has drifted from the code is more dangerous than none: it confidently lies to everyone who relies on it and drags the error into the docs, the SDK and the tests at once. So writing a spec once is not enough — a process is needed that keeps it accurate, and that is what we set up. Also honestly about scope: if you have no API consumers and it is internal and simple, a full maintained specification may be excessive — but as soon as you plan documentation, an SDK or external integrators, the spec becomes the foundation without which building the rest is expensive and crooked. We will say plainly whether you need it already. Picture this: a developer changes a method, CI immediately checks the specification for compliance, and the docs, SDK and playground update from a single source — without manually syncing ten places. The base price starts from 50,000 ₽ for putting it in order; migration from an old format (Swagger 2.0) or a long-abandoned spec, as well as support and CI integration, are costed separately.

• The API description lives in people’s heads and outdated documents — there is no single source.
• Documentation, SDK and tests drift apart — each is edited by hand.
• A specification exists but does not match the real API — it cannot be trusted.
• Any API change has to be manually spread across the docs, SDK, Postman and tests.

• Creating or putting in order an OpenAPI specification (3.x)
• A full description of methods, parameters, responses, errors, authorization
• Linting and quality checks of the specification (consistent style, completeness)
• A link to the code: contract tests, compliance checks
• CI checks so the spec does not drift from the API
• Versioning of the specification
• A single source for documentation, SDK, playground, Postman
• Rules and a process for keeping it up to date

• One source of truth — everything about the API in one formal description
• Docs, SDK, playground and Postman are built and updated from the spec
• The specification matches the real API — it is trusted again
• An API change does not need to be manually spread across ten places

• We look at the real API and the current description, assess the discrepancies
• We bring the specification to the standard, set up linting and contract tests
• We embed the checks in CI, version it, and hand over the process

• Why a separate specification — we already have documentation?

  Documentation and a specification are different layers. The specification (OpenAPI) is a formal, machine-readable description, the source from which documentation, SDKs, a playground and Postman are generated automatically. If you maintain only the documentation by hand, it will quickly diverge from the SDK and tests, because they have no common source. The spec is that common source: you edit it — and everything else updates consistently.

• Won’t the specification drift from the code, as often happens?

  That is the main risk, and it is exactly what we solve. A one-off spec does indeed go stale quickly. So we link it to the code: contract tests and CI checks catch a discrepancy between the spec and the real API during development, not when an angry integrator writes about it. Drift cannot be fully eliminated, but making sure it does not pass silently is realistic. What such checks actually catch: mismatches in methods and fields, response codes, formats and required parameters, missing or extra endpoints. What they will not see is meaning and business logic: whether a method that formally matches the spec actually does the right thing — that is checked by a person.

• Do we definitely need a maintained specification?

  If the API has no consumers and is internal and simple — perhaps not yet, and we will honestly say so. But as soon as documentation, an SDK, a playground or external integrators are needed, the specification becomes the foundation: without it each of those artifacts has to be maintained by hand and they will drift apart. One source is cheaper than syncing five.