The editor's hosts
The API Genie editor edits OpenAPI 3.0, OpenAPI 3.1 and AsyncAPI 3.0 files in forms, on three hosts, with the same page in each:
- Web: the editor’s page in a browser (Chromium, Edge or Firefox), from a folder opened
through the File System Access API or dropped on the page, at https://apigenie.pl/editor/,
which every website deploy rebuilds from
main(ADR-174). - Desktop: the same page in a window of its own. Since 0.12.0, each
cli-X.Y.Zrelease at https://github.com/mykulyak/api-genie/releases has its installers for macOS, Windows and Linux, at the CLI’s version. Around the page, the desktop app adds what needs the machine: the systemgit, a Node.js sidecar for the broker client, and the installedapigenie-serverfor the mock server. The app takes theapigenie-serverthatAPIGENIE_SERVERnames, else one next to the app, else the first onPATH. Outside Windows, it then looks in/opt/homebrew/bin,/usr/local/binand/home/linuxbrew/.linuxbrew/bin. - VS Code: the same page in the API Genie extension’s custom editor, Open with API Genie
Editor (the
ide-X.Y.Zreleases, on the Marketplace from 1.0.0 on). VS Code owns the text, undo, saving, the colours and the code and diff editors; the extension runs the broker client with VS Code’s own runtime, and the mock server with the installedapigenie-server(theapigenie.serverPathsetting, else the first onPATH).
About in the editor’s toolbar says which host you are in, the editor’s version and the host’s own. It gives the addresses of the website and of the releases.
What each host offers
In the tables, same means the feature works as in the web editor; any other cell says what that host does instead, or adds a caveat after same;.
Opening a spec
| Feature | Web | Desktop | VS Code |
|---|---|---|---|
| Open spec… (File › Open Spec… on the desktop): the spec, and the files its references reach | same; needs the File System Access API (Chromium, Edge); elsewhere, drop the spec and the files it refers to on the page | same | VS Code opens files: Open with API Genie Editor |
| Allow access to a folder holding the files a spec’s references name, when they can’t be read | same; needs the File System Access API; the picked file alone can’t reach its neighbours | same | The extension reads the files the spec refers to itself |
| Drop a spec on the page | same; without the File System Access API, drop the files the spec refers to with it; a dropped folder is refused | No drop: open the spec with the dialog or on the command line | VS Code opens the spec: Open with API Genie Editor |
| Start on a spec | A page has no command line: open or drop a spec | same; the spec given on the command line, apigenie-editor <spec> |
The custom editor opens on its document |
| Save files the host can’t write to (dropped files) as downloads | same | same | same |
Toolbar
| Feature | Web | Desktop | VS Code |
|---|---|---|---|
| Undo and Redo | same | same | VS Code’s undo, per document, which also undoes what was typed in its text editor |
| Save, with the count of unsaved files | same | same | VS Code saves its documents; the unsaved marker is VS Code’s |
| Export bundled (the spec and the files it refers to, in one file) | same; needs the openapi_bundle WebAssembly module, which a build with APIGENIE_WASM_DIR ships |
same | same; VS Code asks where to save the bundle |
Mock server (apigenie-server) serving the spec as it is edited |
Runs apigenie-server, which a page can’t start |
same; needs apigenie-server 0.11.0 or later installed |
same; needs apigenie-server 0.11.0 or later installed |
| Theme: the system’s, light or dark | same | same | The VS Code theme’s colours; no setting of the editor’s own |
| The title’s API Genie: a link to the website’s home page, in a new tab | same | A link would take the window away from the editor: the name is plain text; About gives the website’s addresses | The editor doesn’t open links in VS Code’s system browser yet: the name is plain text; About gives the website’s addresses |
| About: the editor’s version, the host and its version, the commit it was built from, and the addresses of the website’s Docs and Downloads pages, of this page and of the GitHub releases | same; the addresses are links, opened in a new tab | same; the addresses are text, to copy | same; the addresses are text, to copy |
Menu bar
| Feature | Web | Desktop | VS Code |
|---|---|---|---|
| Menu bar: File (New, Open Spec, Open Recent, Save, Save As, Close Spec, Exit), Edit (Undo, Redo) and View (Side Bar, Panel, Right Pane), with their shortcuts | A page has no menu bar: the toolbar’s buttons and shortcuts; no Close Spec, since Ctrl+W closes the browser tab | same; Quit is in the application menu on macOS, where Edit also has Cut, Copy, Paste and Select All | same; VS Code’s own menus, where File › Save and Edit › Undo act on its document and View lays out VS Code’s window; API Genie: New Spec… is in the Command Palette and the editor’s title bar |
| File › New…: a new OpenAPI 3.1 or AsyncAPI 3.0 spec next to the open spec, unsaved until Save | No menu bar: create the file outside the editor, then open it | same | same; API Genie: New Spec… in the Command Palette or the editor’s title bar; VS Code creates the file at once |
| File › New… and New spec… with no spec open: the kind, then where to save it, and the new spec opens | No menu bar and no New spec… button: create the file outside the editor, then open it | same | API Genie: New Spec… puts the new spec next to the file open in the editor: open a spec, or an empty .yaml file made with File › New File…, with Open with API Genie Editor first |
| File › Open Recent: the last ten specs opened, and the last one opens again at start | No Open Recent: the editor keeps no spec’s file handle between visits, so Open spec… asks for the spec each time | same; a spec given on the command line opens instead of the last one | VS Code’s File › Open Recent and the editors it restores |
| View › Side Bar, Panel and Right Pane: show or hide each part of the window, with a check on the ones shown | No menu bar: the status bar’s problem counts show and hide the panel; the side bar and the right pane always show | same; Ctrl+B, Ctrl+J and Ctrl+Alt+B (Cmd+B, Cmd+J and Cmd+Option+B on macOS), as in VS Code | VS Code’s own View menu lays out its window; in the editor, the status bar’s problem counts show and hide the panel |
| File › Save As…: the current file’s text, anywhere on disk; a copy inside the spec’s folder joins it | No Save As: a page can only write the files it opened | same | VS Code’s File › Save As… |
| Asks to save unsaved files before closing or opening another spec | Unsaved changes are lost when the tab closes or another spec opens | same | VS Code asks about its unsaved documents |
Panels
| Feature | Web | Desktop | VS Code |
|---|---|---|---|
| API tree: search, filters, add, rename and delete | same | same | same |
| File list with unsaved markers | same | same | same |
| Forms for every node, with the Raw section and quick fixes | same | same | same |
| Preview: the docs of the selected node, OpenAPI and AsyncAPI | same | same | same |
| Flow: the AsyncAPI message flow diagram, editable | same | same | same |
| Changes: the API changes since the last save, with their severity | same | same | same |
| Changes: the text diff since the last save | same | same | Show the text changes in the diff editor opens VS Code’s, on the live document |
| Git tab: status, diff, commit, branches | No Git tab: it runs the system git, which a page can’t | same | No Git tab: VS Code’s Source Control view does that |
Problems: validation and API Genie’s linters (the rules of apigenie lint), under the fields and in the bottom panel’s Problems tab |
same | same | same |
Problems: the linters read commands.lint of the nearest apigenie.yaml, and the ruleset files its extends names, as apigenie lint does. They leave out custom functions and the rules that call them, with a warning. They don’t have the owasp and camara rulesets. Either one in apigenie.yaml’s extends is an error, and the default rules apply. A ruleset that a ruleset file extends and the linters don’t have (owasp, camara, @stoplight/spectral-owasp-ruleset, spectral:oas, an npm package) is left out with a warning; the file’s other rules apply. An extends entry with an absolute path, or a relative path more than 8 folders up, is an error on that entry, and so is a ruleset file that can’t be read or doesn’t parse. The default rules then apply. With no configuration file, a Spectral ruleset (.spectral.yaml, .yml or .json) found in the same places gets an info finding that names Migrate from Spectral |
same; found among the files you dropped with the spec (Open spec… reads the spec alone), or in a folder allowed with Allow access to their folder…, which appears only when a referenced file can’t be read; read when the spec opens; in Safari and Firefox, drop the ruleset files it extends with it, which works only for files beside it (./house.yaml), as dropped files have no folders |
same; found in the spec’s folder, or in a folder allowed with Allow access to their folder…, which appears only when a referenced file can’t be read; read when the spec opens | same; found in the workspace folder, or the spec’s folder outside a workspace, without stopping at a nested Git repository; an edit to it, or to a ruleset file it extends, applies as you type; ruleset files are read only inside the workspace folder, when named .yaml, .yml or .json, and outside node_modules, .git, dist and build |
| Library › My schemas: schemas kept by the editor, dragged to and from schema fields, schema rows and the tree | same; kept in this browser’s storage for the site | same | same; kept in the extension’s global storage |
| Library folders: shared schemas in folders beside the spec folder, referred to by relative $ref | same; needs the File System Access API; you type where the folder is, and allow access again after a reload | same; after a restart, Open shows the folder in the dialog to allow access again | same; set in the apigenie.editor.libraryFolders setting |
Editing
| Feature | Web | Desktop | VS Code |
|---|---|---|---|
Files changed on disk (a git checkout, another editor) are read again when the window gets the focus back; a file with unsaved changes keeps them, the status bar names it, and Save writes over the disk’s version |
same; needs the File System Access API (Chromium, Edge): files dropped in other browsers are not read again | same | VS Code reloads its documents, and the editor follows them |
| Show as code: a node’s text in a code editor, inside its form. On a file’s root form, such as the Specification row’s or a file picked in the file list, the whole file, in place of the form. Show the file as code does the same while the file has syntax errors or no longer holds the node. A Protobuf file has no form: its code shows instead | same | same | Show in the text editor opens VS Code’s at the node; a Protobuf file, and a file with syntax errors, are edited in VS Code’s text editor |
| Import: Swagger 2.0, AsyncAPI 2.x and Postman collections, with the conversion shown as a diff | same | same | Show the conversion in the diff editor opens VS Code’s |
| Ctrl+S / Cmd+S saves | same | same | Asks VS Code to save |
| Ctrl+Z / Cmd+Z and Ctrl+Shift+Z undo and redo | same | same | VS Code’s undo |
Try it out
| Feature | Web | Desktop | VS Code |
|---|---|---|---|
| Try it out: HTTP requests from the operation’s preview | same | same | same |
| CORS proxy setting for servers that refuse the page’s requests | same | same | Not needed: the extension host sends the requests, and CORS doesn’t apply |
| Authorize with OAuth 2.0 authorization-code and implicit flows (a popup) | same | same | same; the authorization page opens in the system browser, which returns to http://127.0.0.1:33418/oauth2-redirect (port in the apigenie.tryIt.oauth2RedirectPort setting): register that redirect URL |
| Send Try it out to the mock server | Runs apigenie-server, which a page can’t start |
same; needs apigenie-server 0.11.0 or later installed |
same; needs apigenie-server 0.11.0 or later installed |
| Try it: publish and subscribe on Kafka, AMQP, MQTT and WebSocket servers (AsyncAPI operations) | Runs a Node.js sidecar, which a page can’t start | same | same |
Host limits
Each difference above comes from something the host can’t do, or does itself.
The web editor has no Git tab, broker Try it or mock server
They run the system git, the broker client’s Node.js sidecar and apigenie-server, which a web
page can’t start. The desktop app and the VS Code extension have them. Their mock server needs
API Genie 0.11.0 or later installed, and names the install commands when it
isn’t. The Git tab, broker Try it and the mock server may come to the web editor later through
integration packages for the frameworks the generators target; none is planned yet.
VS Code has its own text editor, diff editor and Source Control
The custom editor shows no code, of a file or of a node, and no text diffs of its own. Show in the text editor opens VS Code’s text editor at the node, and Show the text changes in the diff editor and Show the conversion in the diff editor open VS Code’s diff editor. The Git tab’s job is VS Code’s Source Control view’s. Undo, the unsaved marker and Save are VS Code’s, since the document is VS Code’s, and the editor takes the colours of the VS Code theme.
VS Code opens folders itself
The custom editor works on the file’s workspace folder, with its other spec files for $refs;
there is no folder picker and no drop. API Genie: New Spec…, in the Command Palette and the
editor’s title bar, does what File › New… does on the desktop with a spec open: the new spec goes
next to the one in the editor. Try it out sends its requests from the extension host, so no CORS
proxy is needed.
The OAuth 2.0 flows with a browser step (authorization code, implicit) can’t return to a webview,
so the extension opens the authorization page in your system browser, and the authorization
server sends it back to http://127.0.0.1:33418/oauth2-redirect, which the extension listens on
only while a flow waits. Register that redirect URL for your client; choose another port with
the apigenie.tryIt.oauth2RedirectPort setting. In a remote window (SSH, a container), the
browser can reach that address only when VS Code forwards the port.