Docs & Code Guide

Embed a diagram in Swagger UI and Redoc: the description field takes markdown

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

An API reference tells a consumer what each endpoint does and almost never tells them what sits behind it. The OpenAPI specification says description fields are markdown, and both Swagger UI and Redoc render them, so a single image line at the top of info.description puts the system picture where integrators are already reading. The mechanics that break it are YAML mechanics and a Content Security Policy, not markdown ones.

Try it free
6 min readFor teams publishing an OpenAPI reference to integrators

See it as a diagram

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

153/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Every description field is markdown

The OpenAPI specification treats description fields as markdown throughout: info.description, the description on each tag, and the description on each operation. Swagger UI renders them and sanitizes the result. Redoc renders CommonMark and additionally lifts first-level headings out of info.description into its side menu, so a heading plus an image gives you an overview section that readers can navigate to.

That makes info.description the natural home for one architecture diagram, and tag descriptions the home for scoped ones. A payments tag can carry the picture of the payments path; an events tag can carry the queue topology behind webhooks.

Nothing about this requires a docs portal product. It works in whatever renders your spec, including the Swagger UI shipped by a framework in development mode.

openapi: 3.1.0
info:
  title: Payments API
  version: "2.4.0"
  description: |
    ## Architecture

    ![Payments architecture](https://datadef.io/api/embed/payments-a1b2c3d4?width=1800&height=1000)

    Requests enter through the gateway, are authorised by the ledger service,
    and settle asynchronously through the events queue.

The YAML mechanics that break the image

The description has to be a literal block scalar, written with the pipe character, so line breaks survive. A folded scalar joins lines together, which glues your image line to the paragraph after it and produces markdown that no longer parses as an image.

Indentation inside the block matters as much as anywhere else in YAML: everything in the block must be indented consistently relative to the key, or the parser truncates the description at the first offending line. If half your overview text vanished, look there before blaming the renderer.

A URL inside a plain scalar contains a colon, which YAML can read as a mapping separator in some positions. Inside a block scalar it is safe, which is one more reason to use the pipe form rather than a single-line string.

What the renderers remove

Both renderers sanitize the HTML they produce from your markdown, and iframes and scripts do not survive that pass. There is no interactive diagram inside an API reference; the image is the embed, and a plain link next to it serves readers who want pan and zoom.

Keep the markup simple for the same reason. An image line, a heading, and a paragraph render identically in Swagger UI, Redoc and the many tools that read the same spec, while anything clever tends to survive in one of them and disappear in another.

The Content Security Policy on your docs host

This is the failure that wastes an afternoon. The spec is correct, the markdown is correct, and the diagram shows as a broken image because the page serving Swagger UI sends a policy with img-src limited to self. The browser console says so plainly, and nothing in the spec file can override it.

API portals are more likely than most sites to ship a strict policy, since they often sit behind the same gateway as the API. Either add the diagram host to img-src, or serve an exported PNG from your own origin and accept that it freezes at deploy time.

The equivalent applies to any docs-portal proxy that rewrites or blocks external references. Test the rendered page, not just the spec, before declaring it done.

Why the address matters here

The spec ships with the service, so a committed picture can only change with a deployment. An address returns the current render at read time, which means the API reference can be right about the architecture between releases. Related: keep API docs in sync with code.

Generating the picture from the spec and the repository

An OpenAPI file already describes a surface: tags, operations, request and response shapes. Turning that into a diagram of the system behind the surface is covered in a living diagram from OpenAPI.

For the fuller picture, connect the repository read-only from GitHub, GitLab or Azure DevOps and let the daily sync regenerate the diagram and an architecture.md from the source, so the drawing in your API reference tracks the services rather than one snapshot of them. See repo to diagram.

One rendering decision is worth knowing if your infrastructure leans on the Terraform Registry. A module whose source is a registry or git address cannot be expanded, because its files are not in your repository, so it becomes exactly one node standing for everything it provisions, labelled with the source and the pinned version from the module block and given an icon inferred from the source string: a source containing vpc draws with the VPC mark, refined to the Azure virtual network mark when the source names Azure. That is the honest rendering. A box reading terraform-aws-modules/vpc/aws at 5.1.2 tells an integrator more than five invented subnets would.

FAQ

Can I put an image in an OpenAPI description field?

Yes. Description fields are markdown by specification, and both Swagger UI and Redoc render them, images included. Use info.description for a system-wide diagram and a tag description for a scoped one. Write the description as a literal block scalar with the pipe character, so the line breaks that make the markdown parse survive the YAML.

Why is my image missing from the rendered API reference?

Two usual causes. In the spec, a description written as a folded scalar or with inconsistent indentation loses the line breaks that make the markdown parse. In the browser, a Content Security Policy on the docs host with img-src limited to self blocks the external image, which the console reports directly.

Can I embed an interactive diagram in Swagger UI or Redoc?

No. Both sanitize the HTML they generate from markdown, and iframes are removed. Show the image in the description and add a plain link for readers who want an interactive view with pan and zoom. The image can still be live, since the renderer fetches the address when the page is read rather than shipping a copy with the spec.

Where should the diagram go: info.description or a tag?

Use info.description for the system diagram, since Redoc lifts first-level headings from it into the side menu and gives readers a navigable overview section. Use tag descriptions for scoped diagrams, such as the path behind one group of endpoints or the queue topology behind webhooks, which would be noise at the top of the page.

Can the diagram change without redeploying the spec?

Yes, when the image is referenced by address rather than committed alongside the spec. The description text ships with the service, while an image URL returns whatever it returns at read time, so the reference can stay accurate between releases.