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 either the Harmony portal menu or the API Manager navigation menu:

• Use the Harmony portal menu to select API Manager > Portal Manager:

  

• When accessing an API Manager page, use its navigation menu to select Portal 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:

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

  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 Manager page allows you to customize the Portal page with an image such as a company logo, or with edits to the automatically generated API documentation:

• Browse Local Files: Click to select an image that meets the listed requirements:

  

  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:

  

• Organization: The Harmony organization currently being accessed.

• Base URL: The base URL for the API service. Click the copy icon to copy the base URL to your clipboard.

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.

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.

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. You can use the interactive swagger to test the API services:

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

• Authorize: If any of the APIs within the selected environment require an authorization set by an assigned security profile, an Authorize button is displayed. Once clicked, a dialog displays any available authorizations. Complete the input as required to test APIs with the provided authorization methods.

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

  

API services¶

Each API service is listed with its method:

The authorization icon indicates whether the API service requires authorization:

• : No authorization is required.
• : Authorization is required.

Click the endpoint row to view information about its parameters and responses – described below.

Try it out¶

On an expanded API service, click the Try it out button to test the API. A configurable API request is expanded:

• Cancel: Click to collapse the configurable API request.

• Execute: Once any request fields are configured, click to generate the Curl and Request URL to use for testing:

  

  • Curl: The cURL request for the values entered for the API request fields. Click the copy icon to copy the cURL to your clipboard.

  • Request URL: The request URL for the values entered for the request fields.

• Clear: Click to clear the values entered for the API request fields.

Possible API responses – those included in the API documentation – are displayed for each API service:

• Server response: Displays any documented server responses.

• Responses: Displays documented HTTP status codes and their descriptions.