Swagger Editor Self-Hosted

Last reviewed Aug 26, 2026 · 735 words

A team I worked with ran Swagger Editor in a container for about 3 years and never backed it up once, because there was nothing to back up. It is a static single-page app: no database, no accounts, no server-side state, and 128 MB of RAM is generous. The spec you type lives in your browser's local storage until you export it. That fact drives everything else about hosting it, including the honest question of whether hosting it beats opening VS Code.

What "editor only" means

Left pane is a YAML or JSON editor with OpenAPI-aware autocomplete and validation; right pane is the rendered documentation, updated as you type, with the same "Try it out" request panel that Swagger UI has. The current generation (the v5 line) understands OpenAPI 2.0, 3.0 and 3.1 plus AsyncAPI 2.x, and its validation catches the things that break code generators: wrong $ref paths, unknown keywords, schemas that are not schemas. Import is drag-and-drop or a URL; export is a file download. That is the whole feature list. There is no mock server, no collaborative editing, no version history and no login.

One container, three environment variables

services:
  swagger-editor:
    image: swaggerapi/swagger-editor:latest
    ports:
      - "8080:8080"
    environment:
      - URL=https://git.example.com/api/team/raw/branch/main/openapi.yaml
    restart: unless-stopped

URL preloads a spec on open; BASE_URL sets a sub-path if you serve it under /editor/ behind a proxy; PORT changes the listening port. A ?url= query parameter does the same as URL per visit, which is how I hand a colleague a link to a specific branch's spec. Because the browser fetches that URL directly, the spec host needs CORS headers permitting the editor's origin, or both need to sit behind the same domain. Nothing else to configure.

The spec belongs in git; the editor is a viewer with a cursor

Since local storage is the only persistence, treat the editor as a scratchpad and the repository as the source of truth. The workflow that held up: openapi.yaml in the API's repository on Gitea, the editor's URL pointed at the raw file on main, and a CI step running a linter (Spectral or Redocly CLI) on every push so that a spec which validates in the editor also passes the team's rules. Edits happen in a branch; the editor is for exploring, and for non-developers who want to see what an endpoint returns without cloning anything. Never let anyone's only copy live in a browser tab.

What fills the gaps it leaves

Publishing the finished spec for consumers is Swagger UI, the read-only sibling, which most API frameworks already embed. Mocking a spec so front-end work can start is a job for Prism from Stoplight or a similar tool, not the editor. Sending real requests during development belongs in Hoppscotch or Bruno, both of which import OpenAPI directly. Collaboration with comments and review is a pull request. Put those 4 together and you have replaced the parts of Postman and Stoplight that a small team actually uses, with the editor as the design surface at the front.

Whether to host it at all

Honest answer: developers mostly should not. The OpenAPI extensions for VS Code and JetBrains give the same validation and preview inline, offline, with git right there. The hosted editor earns its container in 3 cases: non-developers (product, QA, support) who need to read and lightly edit specs; a shared "Try it out" against an internal API that is only reachable from the server's network; and an air-gapped or policy-restricted environment where the public editor at swagger.io is off-limits. If none of those apply, install the extension and move on.

What I'd do

Run the container above behind the same reverse proxy as the internal APIs, preload it from the repository's main branch, and add a forward-auth layer if the specs describe anything sensitive. Keep the spec in git with a lint step, use Swagger UI for the published docs, and Hoppscotch for actual requests. Cost: one 128 MB container and a URL variable. Upkeep: bump the image tag when the OpenAPI version you target changes, which is roughly once every few years.