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.

Accessing the Portal Manager Page¶

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

• From the Home or Downloads pages, or from the Cloud Studio, Vinyl, Marketplace, Management Console, EDI, or Citizen Integrator applications, use the Harmony Portal menu in the top left to go to API Manager > Portal Manager:

  

• From the My APIs, API Logs, Analytics, Security Profiles, Trusted IP Groups, or API Groups pages, use the API Manager 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 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:

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:

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

Authorization¶

If any of the APIs within the selected environment 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 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 submitted request is sent to the endpoint and the response is returned: