OpenAPI / Swagger

OpenAPI / Swagger

An interactive Swagger UI widget for an OpenAPI/Swagger spec, using the same ::: name ... ::: container syntax as every block in Content Blocks - GitBook's own OpenAPI block's direct equivalent. src is resolved the same docs/assets/-relative way ::: file's own src is (see Content Blocks). Both JSON and YAML specs work; Swagger UI parses either entirely client-side; no OpenAPI parsing happens anywhere in this module. Requires bxsites.yaml's openapi set to true - unset, this placeholder renders but stays inert (Swagger UI's own JS/CSS is never copied into site/ at all, keeping every other project's build exactly as small as before this feature existed):

::: openapi src="assets/openapi/example.yaml" title="Bookshelf API"
:::

The widget above is this exact page, live, rendering the small example spec this guide ships at docs/assets/openapi/example.yaml - open it in your own project's docs/assets/ (or point src at wherever your own spec already lives) to see it with your own API instead.

Only SwaggerUIBundle's own base layout is vendored - no topbar/"Explore" bar letting a reader type in a different spec (a ::: openapi block is meant to always show the one spec its author pointed it at), so every operation, its request/response schemas, and "Try it out" (which calls the spec's own servers[0].url directly from the visitor's browser - make sure that server allows CORS from wherever your docs are hosted) render straight from your existing spec with no rewriting needed.

One operation inline

Add operation="METHOD /path" to drop just that one endpoint into a regular page - handy mid-tutorial, without sending the reader off to the full reference:

::: openapi src="assets/openapi/example.yaml" operation="GET /books"
:::

Still the exact same Swagger UI widget as the full block above (same spec, same client-side-only rendering - operation never triggers any OpenAPI parsing on our side either); every other operation is simply hidden and this one auto-expanded, by reading Swagger UI's own already-rendered markup. operation's method is case-insensitive; its path must match the spec's own path exactly ({param} placeholders and all).

Documenting an API without a spec file

::: openapi always needs a real OpenAPI/Swagger document at src - there's no manual, spec-less version of this block for hand-describing a single endpoint. GitBook itself doesn't have one either anymore: its own equivalent, the "API method" block, was deprecated in February 2024 in favor of always importing a real spec. If you don't have one yet:

• Write just enough spec to cover the page you're on. A single paths entry with its own minimal info/servers (see docs/assets/openapi/example.yaml for how little that actually takes) already gets you the interactive widget and "Try it out" for that one endpoint - grow it into a full spec later; nothing about the block itself changes.
• Or skip the widget entirely and describe the endpoint as ordinary content - a parameters table, a fenced ```http /```json request/response pair, walked through with a stepper if that helps. Every other content block and Markdown extension is available on any page regardless of whether openapi is turned on at all.