Edit an API in forms

Not everyone who shapes an API wants to write the YAML of its standard. The API Genie editor shows OpenAPI 3.0, OpenAPI 3.1 and AsyncAPI 3.0 documents as forms, and changes only the lines an edit has to, so a change made in a form reviews like one made by hand. This guide edits an API in the web editor, which runs in the browser with nothing to install.

Open a spec

To try the editor without using your own API, download the Carpet Express OpenAPI 3.1 example.

Open the web editor and choose Open spec… on the file, such as the openapi.yaml of a clone of the repository. The editor reads the files its $refs name with it. In Chrome and Edge, choose Allow access to their folder… under the file list to let it read them, and the changes are saved in place. In other browsers, drop the spec on the page with the files it refers to, and the changes are saved as downloads.

The spec is the file you edit. The files it refers to are shown read-only, so that a change meant for one API doesn’t change every API that shares them; Edit this file on one lets you change it.

The editor works on the 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.

Find your way around

  • The API tree on the left shows the operations, channels, schemas and other parts of the API, with search, filters and a badge where a part has problems.
  • The form in the middle edits the selected part. What a form doesn’t model is shown as raw YAML in its Raw section, never dropped.
  • The Code tab shows the text of the file, and follows the selection.
  • The Preview shows the documentation of the selected part as readers will see it, with Try it out for OpenAPI operations.

References are followed into every file the spec refers to. Renaming or moving a schema, extracting a part into a component or inlining it updates the files that refer to it.

Fix the problems as you go

The editor checks the document as you type: the problems appear under the fields they belong to and in the tree. Besides the standard’s own checks, it applies the linter rules, with a quick fix where a rule has a safe one.

The linters read commands.lint of the project’s apigenie.yaml, and commands.lint.asyncapi for AsyncAPI documents. The editor takes the file nearest to the spec, as apigenie lint finds it when run in the spec’s folder (where the file is found).

The editor reads only what it opened the spec from: the spec’s folder in the desktop app, the files you dropped with the spec in a browser, and the workspace folder in VS Code. Allow access to their folder…, where the editor offers it, widens that to a folder above the spec. In VS Code an edit to the configuration file applies as you type, and so does a file you add or delete; in the desktop app and a browser a change applies when you open the spec again. The editor’s hosts gives the details for each host. When the editor finds no file, the default rules apply, and nothing says so.

Custom JavaScript functions don’t run in the editor yet. The rules that call them are left out, and the bottom panel’s Problems tab says so under the configuration file. A configuration the linter refuses is an error there, and the editor applies the default rules, while apigenie lint stops with exit status 2. The editor checks only version and the lint section: run apigenie config check apigenie.yaml (config) to check the whole file against its schema.

Review the change before you save

The Changes panel lists the API changes since the last save, each rated breaking, non-breaking or non-functional as apigenie diff rates them, and shows the text diff. Save when the change is what you meant; the unsaved files are counted in the toolbar.

Comments, key order, anchors and quoting stay as they were. Opening and saving a file without an edit gives back the same bytes, so the pull request shows only what you changed.

Bring in older documents

Import converts Swagger 2.0 documents, AsyncAPI 2.x documents and Postman collections, and shows the conversion as a diff before it is written.

Other hosts

The same editor runs on the desktop, with a Git panel and a mock server started from the toolbar, and in VS Code, where Open with API Genie Editor opens any OpenAPI or AsyncAPI file. Since 0.12.0, each CLI release on GitHub carries the desktop editor’s installers; the extension ships with 1.0.0. The editor’s hosts lists what each host offers.

Next steps

Was this helpful?