Skip to end of metadata
Go to start of metadata

Introduction

The Portal Manager page allows you to generate OpenAPI documentation for Custom and Proxy APIs. The resulting documentation is displayed on the Portal page, where you can interact with it by testing APIs.

Accessing the Portal Manager Page

The Portal Manager page can be accessed from the Harmony Portal menu, or from other pages within API Manager:

Portal Manager Page Header

The Portal Manager page is also called Manage Developer Portal, as it is the page where you manage what appears on the Portal page (also called Developer Portal). 

These options appear along the top of the Portal Manager page:

  • Navigation: Use the dropdown to navigate between pages of API Manager, including My APIsPortalAPI LogsAnalytics, and Security Profiles.
  • Environment: Click the environment name to open a dropdown to select the environment you want to use for the Portal. This is the environment where OpenAPI documentation will be generated and then displayed on its Portal page. Only a single Portal page for a single environment can be created in each Harmony organization.

    To refresh the environment list, click the refresh icon .

  • View API Documentation: Click the link to go to the Portal page, where the generated interactive API documentation is rendered.
  • Regenerate Docs & Publish: Automatically generates, overwrites, and publishes OpenAPI 2.0 documentation to the Portal page for all Custom and Proxy APIs in the selected environment. OData APIs are excluded. If you have published a new Custom or Proxy API and want to automatically regenerate documentation including any new APIs, you must use this option to generate and publish the documentation on the Portal page.

    WARNING: Using this option overwrites existing API documentation, including any customizations. Before using this option, it is recommended to make a manual copy of the existing API documentation by copying it into an external text editor. After regenerating documentation, manually re-apply any customizations by pasting them into the API documentation editor as appropriate.
  • Save & Publish: Saves and publishes the API documentation to the Portal page. If you have applied any customizations to the automatically generated API documentation, you must use this option to publish the documentation on the Portal page.

Customizing the Portal Page

The Portal page can be customized with an image such as a company logo, or with edits to the automatically generated API documentation.

Adding an Image

To add an image, click the link Browse Local Files and select an image that meets the listed requirements:

The image is automatically published to the Portal page without needing to click Regenerate Docs & Publish or Save & Publish.

To remove an image after uploading, click Remove Image:

Editing the API Documentation

Interactive documentation following the OpenAPI Specification 2.0 is generated automatically for all Custom and Proxy APIs in the selected environment.

The OpenAPI definitions are shown in the editor on the left side of the page and are rendered as interactive Swagger UI documentation on the right side of the page:

You can edit the OpenAPI definitions directly within the editor on the left side of the page. Here are ideas for customizing the documentation:

  • Populate metadata about the API, including Fixed Fields such as title, description, termsOfService, contact, license, and version.
  • Manually overwrite documentation using the OpenAPI Specification 3.0.

After making edits to the API documentation, use the Save & Publish button to publish the documentation on the Portal page.

To regenerate and publish documentation after publishing a new API, use the Regenerate Docs & Publish button.

WARNING: Using the Regenerate Docs & Publish option overwrites existing API documentation, including any customizations. Before using this option, it is recommended to make a manual copy of the existing API documentation by copying it into an external text editor. After regenerating documentation, manually re-apply any customizations by pasting them into the API documentation editor.

Testing APIs

The API documentation generated from the OpenAPI definitions is rendered on the right side of the page. The rendered API documentation is also displayed on the Portal page. You can use the interactive documentation to test Custom and Proxy API calls in order to validate that they are working properly.

Documentation of common Swagger UI elements is provided below. For documentation on all possible elements, see OpenAPI Specification 2.0 or OpenAPI Specification 3.0.

Schemes

Use the dropdown to select from the available schemes supported by the OpenAPI definitions:

Authorization

If any of the APIs require an authorization set by an assigned security profile, an Authorize button is displayed:

On clicking Authorize, a dialog displays any available authorizations. Complete the input as required to test APIs with the provided authorization methods:

Endpoints

Each API endpoint is listed with its method:

The authorization icon on the far right indicates whether the API endpoint requires authorization:

No authorization is required

Authorization is required

Click the endpoint row to expand information about its parameters and responses:

Try It Out

Click the Try It Out button to expand a configurable area:

Configure the request to be submitted to the endpoint, and then click Execute:

The request is sent to the endpoint and the response is returned:



On This Page

Last updated:  Jan 05, 2021


  • No labels