Manage API Documents

You can add markdown content to your API as documents. The documents that you add to your API help the consumers of your API, or API developers, discover and learn about it.
These API documents are in addition to the Swagger API documentation (on the
Spec
tab). They supplement API discovery. 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.
Portal Admins, API Owners, and Org Publishers (for APIs that are assigned to their organization) have Update API permissions and can manage API documents by:
  • Adding them to their API
  • Editing them
  • Deleting them from their API
You manage, or interact, with documents in the navigation tree in API Developer Portal.
Add a Document
Follow these steps:
  1. In API Developer Portal, log in as a Portal Administrator or as an API Owner or Organization Publisher with Edit permissions.
  2. Go to
    Publish
    .
    A list of APIs appears.
  3. Click the API for which you want to add a document.
    The page with Overview information opens.
  4. Click 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. You can use it to access or bookmark the document. By default, the URI includes the encoding. You can remove the encoding. Spaces in URI are replaced with underscores.
    Allowable characters:
    Alphanumeric characters, dashes, underscores, and spaces
    You cannot change the URI once you save this document.
The document is added to the list of documents for the API.
You can view the URI for this newly-created 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.
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 its children.
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
    .