How-to guidesEdit an API in forms

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 folder

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

Open the web editor and choose Open folder… on the folder that holds your API files, such as a clone of the repository. Chrome and Edge save the changes in place; in other browsers, drop the folder on the page, and the changes are saved as downloads.

The editor works on the folder 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 across every file of the folder. Renaming or moving a schema, extracting a part into a component or inlining it updates every file that refers 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 of the repository and your own Spectral rulesets, with a quick fix where a rule has a safe one: the rules apigenie lint applies in CI.

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. Both ship with 1.0.0; the editor’s hosts lists what each host offers.

Next steps