Docs & Code Guide

A living diagram from an OpenAPI spec: the API landscape view that regenerates when the spec changes

An OpenAPI spec is already structured data about your API surface, which makes it the rare documentation source that needs no extraction step at all. Servers name the deployments, tags group the operations, paths enumerate the surface. What the spec does not do is show anyone the landscape: how services relate, what sits behind the gateway, where the seams are. That view is a diagram, and because the spec is versioned text, the diagram can regenerate exactly when the spec changes.

Try it free
8 min readFor API platform teams with specs in the repo

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

205/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The spec already carries the diagram structure

Three spec fields map straight onto a landscape view. servers lists the base URLs, which distinguishes the public edge from internal deployments. tags are the spec's own grouping of operations, orders, payments, admin, and they become the sub-groups inside a service's box. paths enumerate the operations themselves, which the landscape view deliberately does not draw one by one: a diagram with 200 operation boxes is a list wearing a diagram costume.

Since OpenAPI 3.1 there is also a webhooks top-level key, declaring the calls your API makes outward. Those are edges pointing the other way, and drawing them separately from the request surface is exactly the kind of distinction a landscape diagram exists to make.

One spec is a service, many specs are a landscape

The single-spec diagram is the small case. The view engineering leadership actually asks for covers every service: each spec contributes one node with its tag groups, the gateway sits in front, and shared surfaces, auth, webhooks, partner APIs, are drawn once rather than per spec. Collecting the specs is usually trivial, since they live in repos or a developer portal already.

For the first version of that landscape, paste the relevant spec sections or describe the service list at the API architecture diagram generator; it owns the one-off generation intent. This page is about what happens when spec number four changes next Tuesday.

oasdiff is the change detector your CI already wants

Spec changes are diffable in a way code changes are not, and oasdiff is the standard tool: point it at the base and revised spec and it reports what changed, with a breaking-change mode teams already run to protect consumers. That same CI signal is the diagram trigger. When oasdiff reports changes on merge, the job asks an agent connected to Datadef's MCP server (registry io.datadef/mcp) to update the landscape: new tags drawn, removed surfaces dropped, a new server noted. The agent connection needs an API key, available on paid plans.

The honesty clause, as always: Datadef does not watch the repo, and no spec change triggers anything by itself. The loop is the oasdiff step you likely already run, plus one agent command behind it.

# Fail the build on breaking changes
oasdiff breaking specs/main/openapi.yaml specs/pr/openapi.yaml --fail-on ERR

# Human-readable changelog of what changed in the spec
oasdiff changelog specs/main/openapi.yaml specs/pr/openapi.yaml

Spec-first makes the diagram accurate by construction

If your workflow is spec-first, the contract merged and reviewed before implementation, then a diagram regenerated from specs is never behind the API, because the spec change is the API change. Code-first teams get a weaker but still useful guarantee: the diagram is as current as the generated spec, and the gap between code and spec is a separate problem, covered in keep API docs in sync with code.

Credit where due: Swagger UI and Redoc render excellent reference documentation from a spec, one service at a time, operation by operation. The landscape diagram is not competing with them; it is the level above, the view that shows which services exist and how they relate, embedded where architecture decisions get discussed. Client-library docs downstream of the spec are their own workflow, covered in keep SDK docs in sync.

Publish it where developers already read, and the limits

A landscape diagram earns most when it lives in the developer portal next to the reference docs; the ReadMe embed guide covers that platform's specifics. The Datadef embed serves the diagram as a plain image URL with a five minute cache lifetime, so a regenerated landscape appears in the portal within minutes, no page edit involved.

Two limits to state plainly. The embed exists only for projects shared public, so an internal-only API landscape needs that decision made consciously. And the spec describes the API surface, not the runtime topology: which service calls which at runtime is not in any OpenAPI file, and a landscape diagram built from specs should not pretend otherwise. Runtime call edges, if you draw them, come from tracing or from engineers, annotated as such.

Surface, not topology

Specs describe what each API offers, not who calls it. Draw call edges from tracing or team knowledge and mark them as declared, not derived from the spec.

FAQ

How do I visualize an OpenAPI spec as an architecture diagram?

Use the spec's own structure: servers distinguish public and internal deployments, tags group operations into functional areas, and the webhooks key (OpenAPI 3.1) declares outbound calls. Draw the service as a node with tag groups inside it rather than one box per operation. Paste the spec or its structure into an AI diagram generator for the first version, then regenerate on spec changes.

Can I diagram multiple services' specs as one landscape?

Yes, and that is the more valuable view: each spec contributes a service node with its tag groups, a gateway sits in front, and shared surfaces like auth and partner webhooks are drawn once. The inputs are just the collected spec files, which most teams already have in repos or a portal.

How do I detect that an API spec changed in CI?

oasdiff compares a base and revised spec and reports the differences, with a breaking mode (oasdiff breaking, --fail-on ERR) that fails the build on breaking changes. Many teams already run it to protect consumers; the same signal is the natural trigger for regenerating the landscape diagram.

Is this different from what Swagger UI or Redoc do?

Yes. Swagger UI and Redoc render reference documentation for one spec: every operation, parameter, and schema, for developers integrating against that API. A landscape diagram is the level above, showing which services exist and how they relate. Most platforms need both, and they do not overlap.

Does the diagram update by itself when the spec changes?

No. Nothing watches the repository. The loop is one CI step: when the spec diff is non-empty on merge, an MCP-connected agent updates the diagram from the changed spec. Pages embedding the diagram then refresh within minutes without being edited.

Does an OpenAPI landscape diagram show which service calls which?

Not from the specs alone. OpenAPI describes each API's surface, not its consumers, so runtime call edges are not derivable from spec files. Add those edges from tracing data or team knowledge and annotate them as declared, so readers know which parts of the diagram are spec-derived and which are curated.