The editor's Library
The Library is the panel under the file list in the API Genie editor. It holds two kinds of schemas, and you drag schemas between it and the spec:
- My schemas: schemas you keep. The editor keeps them outside your files (ADR-193): in the browser’s storage for the site on the web, in the desktop app’s own storage, and in the extension’s global storage in VS Code.
- Library folders: folders of YAML or JSON files beside or above the spec folder, such as a
sharedrepository checked out next to it. Their files open with the spec folder’s. A$reffrom the spec into them is a relative path,../shared/errors.yaml#/Error, which resolves, renames and inlines like a reference between two files of the spec folder.
Nothing about the Library is written to a spec. Where each library folder is gets kept per spec folder by the host.
Adding a library folder
| Host | How |
|---|---|
| Web | Type where the folder is, relative to the spec folder (../shared), then Add library folder… and pick it. After a reload, Open asks for access again. Needs the File System Access API. |
| Desktop | Add a library folder… and pick it; the editor works out its path. After a restart, Open shows the folder in the dialog to allow access again. |
| VS Code | List the folders in the apigenie.editor.libraryFolders setting, by their path from the workspace folder: ["../shared"]. They open with the editor. |
A library folder sits at most 8 levels above the spec folder, never inside it. ✕ closes a library folder and forgets it; it refuses while a file of the folder has unsaved changes.
A library file lists schemas at its top level, as a shared file of the spec folder does, or under
components/schemas when it is an OpenAPI or AsyncAPI file.
Dragging a schema into the spec
What you drag:
- a row of My schemas;
- a schema of a library folder;
- a schema in the spec: a schema in the tree, the handle (⠿) of a row of the schema editor, the chip of a schema field.
Where you drop it, and what the editor asks when there is a choice:
| Dropped on | From My schemas | From a library folder |
|---|---|---|
A schema field (a request or response body, a parameter, a header, a message payload, items) |
Copy it here, or Add it as a component and refer to it | Refer to it in the library, Copy it here, or Copy it into the components and refer to it |
A row of the schema editor: an object takes it as a new property named after it, an array as its items |
the same as a schema field | the same as a schema field |
The allOf, oneOf or anyOf row of the schema editor |
a new branch, with the same choices | a new branch, with the same choices |
| A spec, or its Schemas, in the tree | a new component, without asking | a copy in the components, without asking |
A schema of the spec dropped on a schema field offers Refer to it and Copy it here.
Use on a row of My schemas adds it to the components of the selected file, as dropping it on that spec in the tree does. Escape, or a click outside the menu, cancels a drop. Each drop is one step of Undo.
What comes along with a copy
A schema that refers to other schemas brings them along: they are added to the components of the
spec, and its references point to them. A component of the spec with the same name and the same
content is used as it is; one with the same name and other content leaves the copy under the next
free name (Category-2), which the status bar reports. A schema that refers to itself becomes one
component.
A reference that leads nowhere in the editor (a URL, a broken $ref) is copied as written, and
the status bar reports it.
Dialects
A copy is converted to the dialect of the file it lands in. What has no counterpart is kept as written, and the status bar names it.
| From | To | Converted |
|---|---|---|
| OpenAPI 3.0 | OpenAPI 3.1, AsyncAPI 3.0 | nullable: true to a null in type (or in enum, without type), boolean exclusiveMinimum and exclusiveMaximum to numbers, example to examples |
| OpenAPI 3.1, AsyncAPI 3.0 | OpenAPI 3.0 | a type list of one type and null to nullable: true, const to a one-value enum, numeric exclusive bounds to boolean ones, the first of examples to example |
| OpenAPI 3.1 | AsyncAPI 3.0 | example to examples; $defs, prefixItems, unevaluatedProperties and the other 2020-12 keywords stay, with a note |
The dialect of a library file is OpenAPI 3.0’s when its schemas use nullable or boolean exclusive
bounds, and JSON Schema 2020-12’s otherwise.
Dragging a schema into the Library
| Dropped on | What happens |
|---|---|
| My schemas | A copy is kept, with the schemas it refers to, under the schema’s name (Order-2 when taken). Keep … in my library in the schema editor does the same. |
| A file of a library folder | Copy it into the file, or Move it to the file and refer to it: the schema leaves the spec, and a $ref to the library takes its place. A component that moves keeps its name and every reference to it follows. |
Move is refused while the schema refers to other schemas of the spec folder, since a library file refers only to its own folder and to other library folders: copy those schemas to the library first. The library file is saved into its library folder with the spec’s files.
Rename and ✕ on a row of My schemas rename and delete it. The search box filters both parts of the Library by name, and a click on a row shows its schema.