Apiary Editor
The Apiary Editor is the foundation of your API design. Apiary Editor supports API Blueprint and Swagger API Description languages.
Overview
Instant validation and live preview enable you to describe, test, share, and collaborate on an API in minutes.
Using the Editor
The Apiary Editor shows a preview of your documentation while providing instant feedback to ensure correct syntax in your API document.
Your API document will be parsed with warnings and errors as you type. These errors will be displayed both in the editor header and on the lines where the warnings and errors exist.
Preview your documentation in the editor: see code samples for interacting with your API, try out the mock server, or make calls to your production server through the console. The Apiary Editor enables you to try out your API design as you write it.
Editor Header
The Editor Header allows for customizing the editor, getting feedback about warnings or errors that may be in your API document, saving and publishing your documentation, and even pushing your document to GitHub.
Feedback and Validations
The Apiary Editor gives you instant feedback on any warnings or errors in your document as you type. The feedback will include line numbers and explanations for the warnings and errors, which will take you to the corresponding line in the editor when clicked. You can also specify custom checks and warnings with the API Style Guide.
Saving, Publishing, and Pushing to GitHub.
The header provides controls for saving and publishing your API document.
Changes in the editor are not saved automatically.
If you have synced your API with GitHub, you can commit and push to GitHub directly from the editor. The sync works both ways: changes to your document on GitHub will be pulled down to Apiary.
Documentation Preview
The documentation preview shows what your API document will look like when rendered as documentation. It also lets you to try out your API as you build. The documentation preview is dynamically updated as you type in the editor.
The mock server will only work with your published changes. This means you will need to save and publish your API to use the changes you’ve made.
Swagger in Apiary Editor
Default format for Swagger in Apiary is YAML. When you paste Swagger in JSON to editor, it will be validated and transformed into Swagger YAML.
Read Only Projects and Branches
In some cases, you might want to prevent edits through Apiary Editor and allow modifications only through Apiary CLI or GitHub Sync/GitHub Integration.
Turning feature on
For both project and branches, this can be done in API Project’s settings.
If you are using GitHub Integration, you can only prevent edits to selected branches. Currently, the edited branch is displayed in the heading of the Settings page.
How do I know if project is read-only?
When project or branch is read-only, a message (instead of buttons) will be displayed in the top right corner.
Also, when you open list of branches, every entry will tell you if it is read-only or not.
This functionality is available only for team API Projects.
Only Apiary PRO plan subscribers can use this feature. If you are interested please contacts us.
Additional References
Ace Editor
Our Apiary Editor is based on ACE. We have customized it to provide feedback for your API document.
Below are some handy ACE keyboard shortcuts. You can quickly see these shortcuts by using Ctrl-Alt-H for Windows or Linux users or Cmd-Alt-H for Mac users.
ACE Keyboard Shortcuts
| PC (Windows/Linux) | Mac | Action |
|---|---|---|
| Ctrl-Alt-H | Cmd-Alt-H | Show Keyboard Shortcuts |
| Alt-Shift-W | Alt-Shift-W | Toggle Word Wrap |
| Ctrl-F | Cmd-F | Find |
| Ctrl-K | Cmd-G | Find Next |
| Ctrl-Shift-U | Ctrl-Shift-U | Change to lowercase |
| Ctrl-U | Ctrl-U | Change to uppercase |
| Alt-0 | Cmd-option-0 | Fold all |
| Alt-L, Ctrl-F1 | Cmd-Alt-L, Command-F1 | Fold selection |
| Alt-Left, Home | Cmd-Left, Home, Ctrl-A | Go to line start |
| Ctrl-P | Ctrl-P | Go to matching bracket |
| Tab | Tab | Indent |
| Shift-Tab | Shift-Tab | Outdent |
| Ctrl-Z | Cmd-Z | Undo |
| Insert | Insert | Overwrite |
| Ctrl-Shift-Z, Ctrl-Y | Cmd-Shift-Z, Cmd-Y | Redo |
| Ctrl-D | Cmd-D | Remove line |
| Ctrl-R | Cmd-Option-F | Replace |
| Ctrl-A | Cmd-A | Select all |
| Alt-Shift-L, Ctrl-Shift-F1 | Cmd-Alt-Shift-L, Cmd-Shift-F1 | Unfold |
| Alt-Shift-0 | Command-Option-Shift-0 | Unfold all |
| Ctrl-Alt-Shift-Up | Ctrl-Alt-Shift-Up | Move multi-cursor from current line to the line above |
| Ctrl-Alt-Shift-Down | Ctrl-Alt-Shift-Down | Move multi-cursor from current line to the line below |
| Ctrl-Alt-Shift-Right | Ctrl-Alt-Shift-Right | Remove current occurrence from multi-selection and move to next |
| Ctrl-Alt-Shift-Left | Ctrl-Alt-Shift-Left | Remove current occurrence from multi-selection and move to previous |