Skip to Content

Portal Manager

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. This page describes the user interface of the Portal Manager page within API Manager.

Limitations

The Portal Manager page has these limitations:

  • Generation of OpenAPI documentation for OData Services is not supported.
  • Generation of OpenAPI documentation for API services using a custom request method is not supported due to a limitation of the OpenAPI specification. APIs that include only custom method API services are shown with an API tag name only.
  • Only a single Portal page for each environment can be created in a Harmony organization.

Access 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 Manage Developer Portal).

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

header

  • Navigation: Use the API Manager navigation menu to navigate between pages of API Manager, including My APIs, Portal, API Logs, Analytics, and Security Profiles.

  • Environment: Use the menu to select the environment where OpenAPI documentation will be generated and then displayed on an organization's Portal page.

    To refresh the environment list, click the refresh icon attachment.

    Note

    Only a single Portal page for each environment can be created in a Harmony organization.

  • View API Documentation: Click to go to the Portal page, where the generated interactive API documentation is rendered.

  • Regenerate Docs and Publish: Click to overwrite and publish OpenAPI 2.0 documentation to the Portal page for all Custom and Proxy APIs in the selected environment. OData Services are excluded. If you have published a new Custom or Proxy API and want to automatically regenerate documentation to include any new APIs, you must use this option.

    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 and Publish: Click to save and publish 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.

Customize 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.

Add an Image

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

upload image browse local files

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

To remove an image after uploading, click Remove Image:

remove image

Edit 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:

openapi documentation

You can edit the OpenAPI definitions directly within the editor on the left side of the page. These are examples of customizations for the API 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, click Save and Publish to save and publish the documentation to the Portal page.

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

Warning

Using the Regenerate Docs and 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.

Test APIs

The API documentation generated from the OpenAPI definitions shown in the editor on the left side of the page, is rendered as interactive Swagger UI documentation on the right side of the page as shown above. 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:

schemes

Authorization

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

authorize

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

available authorizations

Endpoints

Each API endpoint is listed with its method:

api endpoint

The authorization icon indicates whether the API endpoint requires authorization:

  • padlock open : No authorization is required.
  • padlock closed : Authorization is required.

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

endpoint expanded

Try It Out

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

try it out

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

endpoint execute request

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

endpoint response returned