# Edit an API in forms

Source: https://apigenie.pl/docs/guides/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](/samples/carpet-express.openapi-31.yaml).

Open [the web editor](/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 `$ref`s 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](/docs/linter), 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](/docs/concepts/where-the-configuration-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](/docs/reference/editor/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](/docs/reference/cli/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`](/docs/reference/cli/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](https://github.com/mykulyak/api-genie/releases) carries the desktop
editor's installers; the extension ships with 1.0.0.
[The editor's hosts](/docs/reference/editor/hosts) lists what each host offers.

## Next steps

- [Editor](/tools/editor): what the editor does.
- [Lint and format API descriptions](/docs/guides/lint-and-format-api-descriptions): the rules the
  editor applies.
- [Catch breaking changes in CI](/docs/guides/catch-breaking-changes-in-ci): the check that follows
  the pull request.
