The editor's guide

The API Genie editor edits OpenAPI 3.0, OpenAPI 3.1 and AsyncAPI 3.0 documents in forms, and keeps the text as the only source of truth: an edit changes the lines it has to, and the comments, the key order, the anchors and the quoting of the rest stay as they were. Swagger 2.0 documents, AsyncAPI 2.x documents and Postman collections open for import, and Protobuf schemas that an AsyncAPI message names open as code. This guide takes the editor part by part, for its three hosts.

Where it runs

The same editor runs in three places, with the same window in each:

  • The web editor, at api-genie.dev/editor, in Chrome, Edge, Firefox or Safari, with nothing to install. It works on files on your computer: there is no account and no server, and nothing leaves your machine unless you send a request with Try it out.
  • The desktop app, a window of its own on macOS, Windows and Linux. Since 0.12.0, each cli-X.Y.Z release on GitHub carries its installers. Around the window it adds what needs the machine: a Git tab, a mock server run with the installed apigenie-server, and Try it for the brokers of an AsyncAPI document.
  • The VS Code extension, where Open with API Genie Editor opens any OpenAPI or AsyncAPI file in the same window, inside VS Code. The extension is on the Marketplace from 1.0.0 on. VS Code owns the text, the undo history, saving, the colours and the code and diff editors.

The three hosts says what each one adds or does differently, and the editor’s hosts has the whole matrix, feature by feature.

The chapters

Read them in order the first time, or go to the one about the part of the window in front of you.

  1. The window: the toolbar, the side bar, the form, the right pane, the bottom panel and the status bar.
  2. Open and create a spec: a spec and the files it refers to, dropped files, a new spec, saving and closing.
  3. Edit an OpenAPI API: the tree and the forms of an OpenAPI document, from Info to Components.
  4. Edit schemas: the schema editor, its details drawer, references, compositions, extracting and inlining.
  5. Edit an AsyncAPI API: servers, channels, operations, messages, bindings and the message flow diagram.
  6. Work with the code: a node or a file as code, and what the code editor does.
  7. Fix problems: where problems show, where they come from, the quick fixes and the linter’s configuration.
  8. Review and save changes: the Changes tab, saving, and files that change on disk while they are open.
  9. Try it out: requests from the preview, environments, saving a response, the brokers of AsyncAPI and MCP servers.
  10. Mock the API: the mock server started from the toolbar.
  11. Use Git: the Git tab of the desktop app.
  12. Import, export and bundle: Swagger 2.0, AsyncAPI 2.x and Postman collections in, one bundled file out.
  13. The Library: schemas you keep, and shared schema folders.
  14. Keyboard shortcuts: the keys of the window, the tree, the splitters, the code editor and Try it out.
  15. Settings: what the editor remembers, where, and the files in your folder it reads.
  16. The three hosts: the web editor, the desktop app and VS Code, side by side.

The screenshots show the web editor, in the theme of this page. Every chapter has a Markdown copy for agents, at the page’s address plus .md, listed in llms.txt.

Before the guide

Edit an API in forms does one job from start to end: open a spec, change it in a form, review the change and save. The Quickstart installs the command line tools the editor works beside.

Last updated on View as Markdown
Was this helpful?