Manage API Documents

API documents are markdown content that you can add to your API. Portal Admins, API Owners, and Org Publishers (for APIs that are assigned to their organization) have Update API permissions and can manage these documents. Managing API documents includes adding them, editing them, reordering them, and deleting them. These documents help the consumers of your API, or Developers, discover and learn about it.
API documents supplement API discovery and are in addition to the Swagger API documentation that is on the
Spec
tab. For example, you can add documents to your API that cover your performance metrics, functional specs, best practices, and use cases. Categorize and group them in a hierarchy on the Documentation tab.
You manage, or interact, with documents in the navigation tree in
Layer7 API Developer Portal
.
If you have localization requirements, manage your non-English documents using API Hub.
For more information about API Hub, see API Hub.
The following procedures describe how to manage API documents by way of
Layer7 API Developer Portal
. You can also manage API documents by making calls to the Portal API (PAPI)
document-service
resource.
For more information about the PAPI, see Portal API (PAPI).
Add a Document
Follow these steps:
  1. Log in to
    Layer7 API Developer Portal
    as a Portal Admin, API Owner, or Org Publisher (for APIs that are assigned to their organization).
  2. From the menu bar, select
    Manage
    ,
    APIs
    .
    A list of APIs appears on the APIs page.
  3. Click the API for which you want to add a document.
    The
    Overview
    tab opens.
  4. Select the
    Documentation
    tab.
    If the API includes documents, a list of documents appears. Otherwise, the list is empty.
  5. Complete one of the following:
    • To add a top-level document, click the Add Document icon (the + icon).
    • To add a child document nested beneath a parent document, click the ellipsis icon to the right of the parent document, and then select
      Add Document
      .
  6. Add markdown content to your document in the pane to the left, the edit pane.
    The edit pane is a markdown editor. The edit pane and the pane to the right, the preview pane, are a side-by-side view of the document. You can:
    • Copy and paste markdown into your document.
    • Format the content that you add using the options on the menu bar or using markdown syntax.
      For more information about markdown syntax, see the Markdown Guide.
    To preview the content that displays for consumers with read-only permissions to the document, in full-page mode, click
    Preview
    . For example, preview the content to see how the lines will break in the published document. To return the editor view, close the preview.
  7. Click
    Add Document
    .
    The Publish Document window opens.
  8. Enter the following metadata for the document, and then click
    Save
    :
    Title
    The title for the document. This is what shows on the document tree.
    Allowable characters:
    Alphanumeric characters, dashes, underscores, and spaces
    URI
    The Uniform Resource Identifier (URI) is part of the URL. It identifies this document. By default, the URI includes the encoding, that you can remove.
    Allowable characters:
    Alphanumeric characters, dashes, underscores, and spaces
    You cannot change the URI once you save this document. Spaces are replaced with underscores.
The document is added to the list of documents for the API.
You can view the URI for this newly-added document in the web browser’s address bar.
Edit a Document
Follow these steps:
  1. From the list of documents, click the document that you want to edit from the list of documents to select it, and then click the Edit Mode icon (the pencil icon). Your document opens in edit mode, and options on the menu bar display.
  2. Edit the markdown content in the document or add content to the document. You can format the content using the options on the menu bar.
    A preview of your changes shows up in the pane to the right, the preview pane.
    To preview your changes in full-page mode, click
    Preview
    .
  3. Save your changes by clicking
    Publish
    .
Edit a Document's Title
Follow these steps:
  1. From the list of documents, click the ellipses icon to the right of the document that you want to edit, and then select
    Edit Metadata
    .
    The
    Edit Metadata
    window opens.
  2. Edit the title for the document, and then click
    Save
    .
The changes to the document title are saved and published.
Navigate the Wiki Document Tree
You can navigate the document tree using the tab and arrow keys on your keyboard. Move the selector to the document tree using the tab key, then use the arrow keys to navigate through the document tree.
Reorder a Document
You can reorder documents within the document tree, such as moving a document to be a child document of another document or reordering the list of documents.
From the list of documents, click and hold the document that you want to reorder, and then drag and drop it to the new location in the tree.
Delete a Document
Deleting a parent document also deletes the child documents within the document tree (recursive delete).
Follow these steps:
  1. From the list of documents, click the ellipses icon to the right of the document that you want to delete, and then select
    Delete
    .
    The
    Delete Document
    window opens.
  2. Confirm the deletion by clicking
    Yes
    .