User guide

OASForge is a self-contained workbench for OpenAPI documents: a dark-themed Swagger UI preview paired with a YAML editor that validates, autocompletes, searches, imports, exports and mocks — entirely in your browser. Nothing you type ever leaves the page: documents are stored in your browser’s local storage, and the built-in mock server answers “Try it out” requests locally.

Three ready modes are available from the Spec selector in the header: the bundled Demo API (a full OpenAPI 3.1 feature tour), the live Swagger Petstore, and My API — the editor where you write or import your own documents. Supported input versions: Swagger 2.0 (with one-click conversion), OpenAPI 3.0, 3.1 and 3.2.

In editor mode the window splits into the code pane and the live preview. The Editor / Split / Preview switch in the header selects the layout; the divider between the panes can be dragged to resize them, and a double-click on the divider restores the default. Both the split position and the issues-panel height persist across sessions.

The editor keeps any number of named documents in local storage. The document selector in the toolbar switches between them; New starts one from the template, Rename and Delete manage the current one (Delete asks for a second click to confirm). Every keystroke is saved automatically.

Ways to bring a document in and out:

The + Insert menu writes correct OpenAPI structure so you do not have to remember it. Insertions are indentation-aware and land in the right section, which is created when missing; generated names never collide with existing ones, and the placeholder name arrives pre-selected so typing renames it immediately.

Completions appear as you type, or on demand with Ctrl + Space. Suggestions are contextual: operation keys inside a method block, parameter keys inside a - name: item, JSON Schema keywords inside schemas, media types under content:, quoted status codes under responses:.

Value positions complete too: in:, type:, format: and style: offer their legal values, $ref: lists every component defined in the document, and security requirements offer your declared scheme names.

Place the cursor on a schema property, a component schema or a parameter and a small + rule control appears at the end of the line. It lists the validation keywords that fit the declared type — minLength, maxLength, pattern and format for strings, minimum/maximum for numbers, minItems/uniqueItems for arrays, plus enum, default, example and description for any type.

required is handled semantically: for a property it is added to the parent schema’s required list (created on demand); for a parameter it sets required: true. Keywords already present are filtered out of the menu.

The document is linted continuously against the OpenAPI object tables for its declared version. Findings appear in the panel between the code and the status bar; clicking one jumps to its line, which is also tinted in the editor. Errors are structural or semantic violations; warnings flag legal-but-problematic constructs. The preview keeps rendering regardless — validation informs, it never blocks.

Most findings carry a one-click Fix: quoting an unquoted version number, creating a missing security scheme, adding a missing description or responses block, removing a misplaced property, switching the document to the OpenAPI version a keyword requires, and more.

Messages are version-aware across Swagger 2.0 and OpenAPI 3.0–3.2: a 2.0 keyword in a 3.x document names its modern replacement, a 3.1-only feature in a 3.0 document offers a version bump, and constructs the specification ignores (such as a header parameter named Authorization) are explained.

Warnings can be dismissed individually with their close control; dismissals are remembered per document and the status bar keeps an honest count (for example “Valid — rendering live (2 hidden)”). A footer row restores all hidden warnings at once. Errors cannot be dismissed. The panel’s height is adjustable by dragging its top edge.

In the code. Ctrl/Cmd + F — or the magnifier button in the toolbar — opens the find bar. Matches highlight live with a position counter; Enter and Shift + Enter cycle forward and back, Esc closes. A selection made before opening becomes the initial query.

In the preview. The search field above the operations searches the parsed document, not just what is visible: paths, methods, summaries, descriptions, tags, operation ids, parameter names, media types, status codes, security scheme names, and schema property names and enum values with $refs resolved. Multiple words must all match. Tag sections whose operations are all filtered out disappear; a counter reports the visible share, and Esc clears the query.

Preview to source. In editor mode, clicking an operation header or a schema name in the preview scrolls the editor to the corresponding lines.

Every operation’s Try it out works immediately: the default server entry is an in-browser mock, so requests are answered locally from your schemas and examples and never leave the page. The mock is stateful — POST creates records held in memory, GET lists or returns them, PUT/PATCH update, DELETE removes. Endpoints without stored data respond with examples derived from their schemas.

Your own servers stay selectable in the Servers dropdown, including a free-text entry for any base URL such as http://localhost:3000. Real servers must allow cross-origin requests from the page.

Postman collections (v2 / v2.1 exports) are converted to OpenAPI 3.0.3 automatically when pasted, opened as a file or fetched from a URL. The conversion covers: folders as tags, the collection base URL as a server, all authentication types (API key, Bearer, Basic, OAuth2 with the matching flow — a raw Authorization header also becomes a bearer scheme), path and query variables, JSON, form-urlencoded, multipart, GraphQL and XML bodies, and every saved response: one per status code becomes its example, several variants of the same code become named examples shown as a dropdown, and meaningful response headers are documented while transport noise is dropped. Conversion is lossy in the Postman direction (scripts and tests are not representable), so imports are saved as a new document.

Swagger 2.0 documents are recognized and render as-is; a banner under the editor offers a one-click conversion to OpenAPI 3.0 — servers from host/basePath, body and form parameters to requestBody, definitions to components, references rewritten.

The History control keeps compressed snapshots of each document: one is recorded automatically after meaningful changes (rate-limited), and Snapshot now stores one on demand. Up to twenty snapshots are kept per document in local storage.

Each entry offers Restore — the current state is snapshotted first, so restoring is itself reversible — and Diff, a color-coded line comparison against the current text.

The site is fully static and self-contained — all third-party assets are vendored, so it works offline and in air-gapped networks. Any static file server can host it:

python3 -m http.server 8000
# or, with Docker:
docker compose up   # http://localhost:8080

A single-file build is also published alongside the site as standalone.html: the entire application — scripts, styles, vendored libraries and the demo spec — inlined into one file that runs from file:// with no server and no network. Download it once and keep it anywhere; it is rebuilt on every deployment, so a fresh download is always current.

The site is also an installable application: browsers that support progressive web apps offer an install control in the address bar (or “Add to Home Screen” on mobile). The installed app opens in its own window and keeps working without a network connection — a service worker caches the entire application on first visit and refreshes it in the background on later loads.

Documents, snapshots, dismissed warnings and layout preferences live in the browser’s local storage of whoever is using the page; the server stores nothing.

The project is available under the Elastic License 2.0. In short: free to use, copy, modify and embed — commercially included — but it may not be offered to third parties as a hosted or managed service, license notices must stay intact, and license-key functionality may not be circumvented. Vendored third-party assets keep their own licenses. See the LICENSE file in the repository for the full text.

OASForge — formerly Swagger Dark UI — is designed, built and maintained by Kaan Dikeç — from the dark theme and the demo specification to the in-browser validator, mock server, converters and exporters. It is an independent open-source project.

Copyright 2026 Kaan Dikeç. Licensed under the Elastic License 2.0.