DEV Community: Octri

Why generated SDKs break silently, and how to make them observable

Octri — Fri, 09 Oct 2026 14:23:19 +0000

You generate an SDK from your OpenAPI spec, publish it to npm and PyPI, and integrators start building on it. Then it goes dark.

Once that client library is running inside someone else's production application, you have almost no visibility into how it behaves. An endpoint starts returning a shape the SDK doesn't expect. A serialization path throws for a subset of inputs. A retry policy turns a blip into a storm against your API. And the first you hear about any of it is a GitHub issue, a support ticket, or a customer who quietly churns without ever filing one.

We instrument our servers exhaustively. We wrap our own front-ends in Sentry. But the SDKs we ship to other developers, arguably the most important surface of an API product, are the one place we fly completely blind.

Why "just add Sentry" never happens

In principle, every integrator could wrap your SDK in their own error monitoring. In practice they don't, and even when they do it doesn't help you:

It's their Sentry, not yours. The errors that reveal a bug in your SDK land in dozens of separate customer dashboards you'll never see.
The stack traces are useless. They point into minified, bundled SDK code your integrator doesn't own and can't read.
There's no shared release identity. Nothing connects the code you generated to the build the error came from.

So the signal that would tell you your SDK has a problem is scattered, minified into noise, and invisible to the one team that could fix it: you.

What "observable generated SDKs" actually requires

Three pieces have to line up. Miss any one and you're back to guessing.

1. Runtime error reporting from inside the SDK

The generated client captures failures and reports them with context: endpoint, status, SDK version, and, critically, a release tag. Only the SDK author can build this in. It has to live in the generated code itself. In Octri this is a toggle plus an SDK rebuild, since the telemetry config is compiled in at build time: see Setup.

2. Source maps, uploaded from the right build

A minified stack trace is noise until you pair it with the source map from the exact build that produced it. Here's the part that trips people up. Those maps get produced when the application bundles, in your integrator's CI, on every deploy. Not when the SDK is generated. So they have to be uploaded separately, tagged with the same release. It's the model sentry-cli sourcemaps upload already uses. Minified languages upload source maps; compiled ones like Go, Rust, and Java upload sources instead.

3. Release pairing on read

When an error arrives tagged release: abc123, the service looks up the source map tagged abc123 and de-minifies the trace against it. The match is the whole trick. Get the tags out of sync and every trace resolves to nothing.

The one rule that makes it work

The release your SDK reports at runtime must equal the release you tagged when you uploaded source maps. In practice, that's the git SHA of the same build. That one invariant is what lets an incoming production error pair with the right map and de-minify to your original source. Everything else is plumbing. This is the load-bearing constraint.

If you're implementing this on Octri rather than reading it as theory, readable stack traces is the guide for exactly this rule, including how to check the release with --dry-run before you deploy and why you should never serve those maps to users. CI setup puts the upload on every build.

What you get once it's wired up

A production error in a customer's app arrives as a clean, de-minified stack trace that points straight at your source. Errors group into issues, so one bad deploy is one problem rather than a thousand.
You can see which endpoints break for real integrators, ranked by frequency. It's a prioritized bug list you never had to ask anyone for.
You fix integration bugs before they turn into tickets, bad reviews, or churn. Ship the fix and watch that build in releases, or alert on the error budget so the next one finds you first.

The takeaway

SDK generation shouldn't end at "here's your client library." Shipping the library is where its real life begins. The most interesting failures happen out there in production, in code you generated but don't run. Treat generated SDKs like any other production surface. Make them observable.

This is the bet we made with **Octri. Every SDK it generates from your OpenAPI spec carries opt-in runtime reporting, plus a source-map upload command in the octri CLI and release pairing. SDK users turn reporting on. Docs and SDKs in 10 languages, monitored, from one spec. Try it free on your own spec.

Read next: the monitoring docs for how it works in the dashboard, or Inside Octri Monitoring for a tour of the views you get.

Publishing SDKs to npm, PyPI, Maven Central and the rest

Octri — Fri, 09 Oct 2026 14:18:01 +0000

Generating a client library is the easy half. Getting it into the place your users already look, under a name you can live with, is where the irreversible decisions are.

Most of them are naming decisions, and every registry punishes a bad one differently.

The registries, and what each wants

npm, for TypeScript. Scoped (@acme/api) or unscoped (acme-api). Take the scope. It is namespaced to your organisation, it cannot be squatted, and it reads unambiguously beside your other packages. npm has no rename, and it refuses to republish a version you have deleted, so the first publish claims the name permanently.

PyPI, for Python. The distribution name is what users type after pip install. It is normalised, so acme_api and acme-api are the same name to the index and you cannot have both. The import name is a separate thing and does not have to match, which surprises people: pip install acme-api giving you import acme_api is normal and fine.

Maven Central, for Java and Kotlin. Coordinates are groupId:artifactId, and the groupId must be a domain you control. Sonatype verifies it before your first release, not after. com.acme means proving you own acme.com. This is the single longest lead time in any SDK launch and it is the one nobody schedules for, because every other registry lets you publish in five minutes.

crates.io, for Rust. Flat namespace, no scopes, first come first served. Names are effectively permanent. Reserve yours early even if you are not ready to publish.

RubyGems, for Ruby. Flat namespace too. Convention is dashes in the gem name and slashes in the require path.

Packagist, for PHP. vendor/package, wired to a git repository rather than an upload. Composer resolves from tags, so your release process is a tagging process.

pub.dev, for Dart. Flat namespace, and it scores packages publicly on documentation and maintenance. That score is on the page your users read, so the README is not optional in the way it is elsewhere.

Go and Swift have no registry

This catches people out because it inverts everything above.

Go modules and Swift Package Manager resolve straight from a git repository. There is no account to connect, no upload, no publish step. You push a tagged commit and go get finds it.

Which sounds simpler and is more dangerous, because of one thing:

For Go, the repository URL is the import path. Go derives the module path from the repo and writes it into go.mod, so github.com/acme/acme-go is the line every consumer types at the top of their file. Rename or move that repository and every import breaks, for everyone, with no deprecation path and no redirect. There is no equivalent of an npm deprecation notice.

Pick the Go repository name deliberately, before the first tag, and expect it to differ from the repository your other languages use. acme-go is a repository name. acme-node is a different one. They should not be the same repo.

One repo per language, or one repo for all

Both work. The tradeoffs are not symmetric.

Separate repositories per language are the default for a reason: Go forces it (the import path is the repo), release tags do not collide, each language gets its own issue tracker, and a consumer cloning your Python SDK does not download six other languages.

A monorepo is tidier for you and worse for them. If you go that way, Go still needs its own, so you end up with a monorepo plus an exception, which is usually the worst of both.

What to settle before the first publish

A short list, all of it permanent or expensive to change:

The package name in every registry. Check availability everywhere at once, before you pick. Discovering that your name is taken on crates.io after you have shipped on npm means either an inconsistent set of names or a rename.

The Maven groupId, and start the verification. It gates your Java launch and it is out of your hands.

The Go repository. See above.

The version you start at. 1.0.0 is a claim about stability. 0.1.0 buys room to change the shape of the client while people are still evaluating. Starting at 1.0.0 because it looks committed is how teams end up doing a major bump in month two.

Who owns the credentials. Registry tokens are long-lived and they publish under your organisation's name. They belong in your secret manager with an owner, not in one engineer's shell profile.

Automating it

Publishing by hand works exactly until the release where somebody forgets one language, and then you have five SDKs on 2.1.0 and one on 2.0.4, and the one that lagged is the one someone reports a bug against.

The property worth having is that a release is one action producing every package, with the version coming from a single source rather than from six manual edits. If your version lives in your OpenAPI document and propagates into every generated manifest, the manifests cannot disagree with each other.

On Octri, connecting each registry account is a one-time step and releases go out on publish, with Go and Swift handled through the GitHub App rather than a registry token. Automatic publishing is a Business-tier feature; on the tiers below it, the packages are generated and you publish them yourself, which is the same artifacts with a manual last step.

Before you press publish

Read the package. Not the code, the packaging: what files are included, whether the README renders, whether the license is there, whether the version matches what you think you are shipping. Every registry makes at least one of those easy to get wrong, and all of them are visible on the page your users land on.

If you have not decided which languages to ship yet, the OpenAPI to TypeScript SDK and OpenAPI to Python SDK pages show what the generated client looks like at the call site in each. And before any of it, the spec audit tells you whether your document is in a state to generate something worth publishing.

How to Generate API Documentation from an OpenAPI Spec (2026 Guide)

Octri — Fri, 09 Oct 2026 14:16:36 +0000

Good API documentation decides whether a developer integrates your API in an
afternoon or gives up before lunch. The reliable way to get there is to
generate your documentation directly from your OpenAPI specification. This
guide covers the whole path, from writing the spec to hosting docs that update
themselves.

What is an OpenAPI spec?

An OpenAPI specification (formerly Swagger) is a machine-readable document,
written in YAML or JSON, that describes every endpoint your API exposes: paths,
parameters, request bodies, responses, authentication and data models.
Because it is structured data, tools can read it and generate documentation,
client SDKs, mock servers, and tests from a single source of truth.

If you already have an openapi.yaml or swagger.json, you are ready to
generate docs. If not, most modern frameworks can emit one for you.

Why generate docs from the spec instead of writing them by hand?

Hand-written documentation has one fatal flaw: it drifts. Add a field or change
a status code and the prose is wrong. Nobody notices until a customer files a
ticket.

Generating docs from the spec flips that around:

One source of truth. The spec describes the API; the docs are derived from it, so they can never silently disagree with the contract.
Speed. A complete reference site comes out of one command.
Consistency. Every endpoint is documented the same way, with the same structure for parameters, responses, and errors.
Free downstream artifacts. The same spec generates SDKs, Postman collections, and mock servers.

Treat your OpenAPI document like source code: review it, lint it, and keep it in version control. Everything downstream inherits its quality.

Step 1: Write and validate your OpenAPI spec

Start from a small, correct spec and grow it. Here is a minimal but valid
example:

openapi: 3.1.0
info:
  title: Invoices API
  version: 1.0.0
paths:
  /invoices:
    post:
      operationId: createInvoice
      summary: Create an invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvoiceInput"
      responses:
        "201":
          description: The created invoice.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
components:
  schemas:
    InvoiceInput:
      type: object
      required: [amount, currency]
      properties:
        amount: { type: integer, description: Amount in the smallest currency unit. }
        currency: { type: string, enum: [usd, eur, gbp] }
    Invoice:
      allOf:
        - $ref: "#/components/schemas/InvoiceInput"
        - type: object
          properties:
            id: { type: string }

Before generating anything, validate the spec in CI so a broken document can
never ship:

npx @redocly/cli lint openapi.yaml

Step 2: Choose how you'll generate the docs

There are three broad approaches. Pick based on how much control and automation
you need.

The first two are fine for a spec that rarely changes. If your API changes every
release, pick an approach that regenerates docs from the spec on each push.
Otherwise you are back to manual drift.

Step 3: Generate the documentation

With a validated spec, generating a reference site is a single command with most
tools. The output is a set of static pages describing every endpoint, grouped by
tag, with request/response schemas rendered from your components.

The quality of that output is bounded by the quality of the spec. That is why
the next section matters more than the tool you pick.

Step 4: Host the docs and wire up search

Documentation only helps if developers can find and read it:

Serve it on a fast, cached URL (a CDN or a static host). On Octri that URL is live from your first upload, and a custom domain moves it to your own hostname.
Add full-text search so readers can jump straight to an endpoint. See search and AI chat, which also answers reader questions from your published pages.
Include copy-paste code examples and, ideally, a live "try it" console.
Expose an sitemap.xml and clean canonical URLs so search engines index every endpoint page. See SEO.

Step 5: Keep the docs in sync automatically

This is the step teams skip, and the reason so many API docs are subtly wrong.
Connect documentation generation to your pipeline so it re-runs whenever the spec
changes:

A push updates openapi.yaml.
CI validates the spec.
Docs regenerate from the new spec.
Only the pages that changed are rebuilt and re-published.

Once that loop runs, the reference stays current without anyone maintaining it.

Best practices for generated API docs

A few habits make a large difference to the generated output. We go deeper on
these in Ten Habits for Writing Great OpenAPI Specs:

Give every operation an operationId. It becomes the anchor link and the SDK method name.
Write real description and summary fields. "Returns the authenticated user's profile" beats "Get user."
Add examples to request bodies and responses. They flow straight into the docs and the try-it console.
Model your errors explicitly with documented 4xx/5xx responses.
Reuse components with $ref so shared schemas render consistently.
Tag operations into logical groups so the sidebar has a sensible order.

Common mistakes to avoid

Documenting only the happy path and omitting error responses.
Leaving operationId blank, producing unreadable anchors and SDK names.
Editing generated HTML by hand. Your changes vanish on the next build.
Letting the spec and the running API diverge because nothing validates them.

Frequently asked questions

Is OpenAPI the same as Swagger?

Effectively yes. "Swagger" was the original name; the specification was donated
to the OpenAPI Initiative and renamed OpenAPI. Swagger now refers to a set of
tools built around the OpenAPI spec. You can read the current specification at
spec.openapis.org.

Can I generate SDKs from the same spec?

Yes. The same OpenAPI document that produces your docs can generate typed client
libraries in many languages. SDKs and docs then come from one contract and cannot
disagree. Octri does ten of them, documented in the SDK guides,
and can publish each one to
its native registry.

How do I stop my docs from going out of date?

Automate generation in CI so docs regenerate from the spec on every change, and
publish only the pages that changed. Manual rebuilds are where drift
creeps in.

Do generated docs help with SEO?

They can, if each endpoint gets its own crawlable page with a clean canonical
URL, descriptive titles and a sitemap. That turns your reference into hundreds
of indexable, long-tail landing pages. Octri emits a canonical URL per page and
derives sensible titles on its own; the SEO guide
covers what you can override, including Open Graph images and whether a project is
indexable at all.

Turn your spec into docs

You don't have to wire this pipeline together yourself. Octri takes your
OpenAPI spec, generates documentation and production-ready SDKs, and keeps both
in sync on every push.

Create your first project, or read the
docs to see how it works.

Should you hand-write your SDKs or generate them?

Octri — Fri, 09 Oct 2026 13:47:52 +0000

The case for hand-writing is better than generation advocates admit, and it has a shape.

A hand-written client can be idiomatic in ways a generator cannot reach. It can name a method after what your users call the thing rather than after your operationId. It can collapse three endpoints into one convenience call because that is how the workflow actually goes. It can have a helper that does the retry-and-poll dance your API requires and your spec does not describe.

If you ship one language, your API changes a few times a year, and you have someone who cares about that library, hand-writing produces a better artifact. That is the honest version.

The problem is that almost nobody stays in that situation.

What actually breaks it

Two variables, and they multiply.

Languages. One library is a craft project. Six is a maintenance obligation, and the sixth is always the one nobody on the team writes daily. Your Rust SDK gets written by whoever was free, and it gets updated at whatever rate that person has time for.

Change rate. An API that changes monthly means every change lands six times. Miss one and you have SDKs that disagree about what your API does, which is worse than having fewer SDKs.

Multiply them and you get the failure everyone recognises: the TypeScript client is current because that is what the team uses, Python is one version behind, and Ruby has an open issue from March saying a field is missing.

The 2026 drift data puts numbers on the pressure. 41% of APIs see schema drift within thirty days, and 86% of those events are field additions, which are exactly the changes nobody remembers to propagate because nothing breaks when you skip them. Six hand-written clients means six chances to skip.

What generation is actually good at

Not the method names. The parts nobody enjoys writing and everybody gets subtly wrong on the fifth language:

Consistency across languages. One retry policy, one pagination contract, one auth mechanism, emitted six times. Teams that hand-write six clients write six retry policies, and by year two they disagree about which status codes are safe to repeat.

The unglamorous correctness. Backoff with jitter, per-attempt timeouts, idempotency keys on writes, typed errors split by cause. Every client needs these and hand-written ones acquire them incrementally after incidents.

Keeping up. A field added to a response appears in every language on the next generation, without anyone remembering.

Reaching languages you do not staff. You probably do not have a Dart developer. Your Flutter users still want a client.

What generation is bad at, and what to do about it

This is the part worth being straight about, because it is where the objection lives.

Generated names can be bad. They come from your operationIds, and if those were written for a linter rather than a call site you get client.actions.actionsActionsGet(). The fix is not to hand-write the client, it is to fix the ids or override the generated method name per endpoint. Both are cheaper than maintaining a library.

Generators do not know your workflows. If using your API means "create, then poll until ready, then fetch", no generator will produce the helper that does it. That helper is real value and it has to be written.

Generated code can be ugly. Sometimes true, and it matters less than people think because most consumers read the method signature and the types, not the transport layer.

The synthesis most teams land on is the useful one: generate the client, hand-write a thin layer of workflow helpers on top of it. The generated part tracks your API automatically and the hand-written part is small enough that one person can own it in every language you care about. You get idiom where idiom matters and coverage everywhere else.

The decision, plainly

Hand-write if you ship one or two languages, your API is stable, and someone owns the library as part of their job rather than as an occasional errand.

Generate if you ship three or more languages, or your API changes more than quarterly, or you want to support a language nobody on your team writes.

Generate plus a helper layer if your API has multi-step workflows worth wrapping, which is most APIs past a certain size.

The crossover is lower than instinct suggests, because the cost of a hand-written SDK is not the writing. It is the year of small updates afterwards, paid in the languages you are least equipped to maintain.

The question that settles it

Ask what happens the next time you add a required parameter to an endpoint.

If the answer is "I update the spec and every client regenerates", you are fine. If it is "I update the spec, then open six repositories", you already know which of the six will be late, and your users will find out before you do.

If you want to see what generated output actually looks like before deciding, the OpenAPI to TypeScript SDK, Python, Go and Java pages show the call site each one produces from the same document, including the default client shape and what you can change about it.

And whichever way you decide, the spec audit is worth running first, because a document that scores badly produces a bad generated client and a hand-written one built on the same missing schemas will have the same gaps, only hidden behind code somebody wrote.

MCP vs OpenAPI: they answer different questions

Octri — Fri, 09 Oct 2026 13:38:30 +0000

The question gets asked as though one is replacing the other, and the framing is wrong in a way that leads teams to build the wrong thing.

OpenAPI is a description. It is a document that says what your API accepts and returns, read by humans, code generators, linters and documentation tools. It is static, it is versioned, and it describes the whole surface whether or not anyone uses it.

MCP is a protocol. It is a live conversation between an assistant and a server, in which the server offers a set of tools and the assistant calls them while it works. It is dynamic, it is scoped to a session, and it carries only what an agent should be able to do right now.

One is a blueprint. The other is a set of keys. Asking which to use is like asking whether to have architectural drawings or door access.

Why the comparison keeps happening

Because in practice a lot of MCP servers are generated from OpenAPI documents, which makes them look like two formats for the same thing.

They are not, and the generation step is doing real work. It is selecting which operations become tools, naming them for an audience that reads names rather than paths, writing descriptions aimed at a model deciding which tool to reach for, and deciding what an agent is allowed to touch. A spec describes 300 endpoints. A good MCP server might expose 30 of them.

That selection is the product. If your MCP server is a mechanical one-to-one dump of your spec, you have converted a format and skipped the part that mattered.

What OpenAPI is better at

Being complete. A spec covers every operation including the ones nobody should call from an agent, the deprecated ones, the internal ones. Completeness is the point. It is the contract.

Generating things. Documentation, client libraries, mock servers, validation middleware, test scaffolding. Every one of those wants the full typed surface, and none of them wants a curated subset.

Being reviewed. A spec sits in a pull request. Someone can see that an operation gained a required parameter. There is no equivalent review surface for "what my agent can do today" unless you build one.

Living without a runtime. A spec is a file. It works when nothing is running, which is how a developer reads your API at 2am before deciding to integrate.

What MCP is better at

Being current. An agent asking a live server gets the answer as of now. A spec pasted into a context window is a snapshot that started going stale the moment it was pasted.

Being selective. Context is finite and expensive. A protocol that lets an agent ask for one endpoint's detail beats one that requires it to hold a megabyte of JSON to answer a question about one call.

Executing. This is the part with no OpenAPI equivalent. A spec tells an agent what a request would look like. A tool call makes the request and returns the response, which collapses the loop between writing code and finding out whether it works.

Carrying the things a spec cannot. Your written guides, your changelog, the real method names in your published SDK. None of that is in your OpenAPI document, and all of it changes what an agent writes.

The relationship in one line

Your OpenAPI document should be the source both come from, and your MCP server should be a curated projection of it.

That ordering matters. Teams that hand-build an MCP server separately end up with two definitions of their API that drift, and the agent-facing one drifts faster because nothing compiles against it. Teams that generate the tools from the spec get one source of truth and a curation layer on top.

The curation layer is not optional, and it is where the judgement lives:

Which operations become tools. Exclude anything irreversible, anything administrative, anything an agent has no business calling. The exclusion list you wrote for your public SDK is usually close to right.

What the tools are called. A tool name is read by a model choosing between options. create_invoice is a choice. postV1InvoicesCreate is a transport detail.

What the descriptions say. This is the highest-leverage text in the whole system and it is usually copied from a spec summary written for a documentation page. A tool description is a decision aid: when should the model use this instead of the other one.

When you need only one

You need only OpenAPI if nothing is calling your API through an assistant. That is a shrinking set, and it is a real set.

You need only MCP if you are exposing something that is not an HTTP API at all, which is the case for plenty of MCP servers: file systems, databases, internal services with no public contract. There is no spec to generate from, and hand-writing the tools is correct.

For an HTTP API with an OpenAPI document, wanting one and not the other is almost always a sequencing question rather than a choice. The spec comes first because everything else derives from it.

The practical test

Ask what happens when you add an endpoint.

If your documentation, your client libraries and your agent tools all update from that one change, the relationship is right. If adding an endpoint means editing a spec and then separately editing an MCP server, you have two sources of truth and you will find out which one is stale at the worst moment.

That is the whole argument for generating both from one document, and it is why Octri treats the spec as the input and the docs, the SDKs and the MCP server as outputs of it. One change, four surfaces, no drift between them.

If you want the mechanics of the second half, generating an MCP server from an OpenAPI spec covers the setup. And if you are not sure your spec is in a state to generate anything useful yet, the spec audit scores it against the fourteen rules that decide, free and without an account.