Editing your APIs

Learn about how to curate your services in Appear's Catalog editor

The block editor offers an intuitive interface for managing your API catalog effectively when maintaining API documentation in Appear.

This guide will walk you through editing service, endpoint names, descriptions, and other modifiable elements.

Editing service or endpoint names

1. Service and Endpoint Names:

   • To edit names or descriptions, simply click on the text you wish to change and enter an appropriate name

   • Your changes are auto-saved and will be reflected in all locations referencing the service or endpoint

Editing service, endpoint, and response descriptions

Appear gives you a strong starting point to further curate your services by generating descriptions of your services, endpoints, and responses.

Appear's block editor is visible when you click in an editable area, like the 'description' space at the top of the column.

There are some key areas you can edit within the Catalog. There are visible when you click into the description area at the top of your service, endpoint, or response columns.

Working with Tags, Owners, and Servers

1. Tags:

   • Tags are free-text elements that can be added to categorize or label your services and endpoints. To add a tag:

     • invoke the block editor menu by entering /

     • Select 'Tags' from the menu

     • Enter '#' and then the name of the tag

     • Press enter

   • Tags help filter and search the catalog, making managing and navigating extensive API collections easier.

Invoking the block editor menu is done via typing the forward slash key '/'

1. Owners:

   • Owners can be assigned to each service or endpoint. These are the members of your team who own and are responsible for the service.

   • If the owner already exists in the organisation’s account list, you can select them from a dropdown menu. If not, you can create a new 'owner' (user) by typing their name and selecting the option to add.

2. Servers:

   • Servers associated with each service or endpoint are detected automatically. However, if needed, you can manually insert additional server details to ensure that all potential runtime environments are covered.

   • To edit or add server information, press / (forward slash) to invoke the block editor menu and choose the 'Servers' item. Enter in the server URL and Appear will begin checking that URL for reports from the package.

Inserting and Formatting Content

• To add new content blocks such as bullet lists, numbered lists, or code blocks, click the / button within the Catalog description areas. Just select the appropriate content type from the menu and place it where needed in your document.

• For structured content like tables or to insert columns, use the respective options from the insert menu to enhance the layout and presentation of complex data.

Important Tips

• Not all sections in the Appear documentation are editable. Pay attention to the interface cues, as some fields may be locked based on the configuration settings or user permissions.

• The editor will automatically save changes as you curate your services and endpoints