Customize a Developer Portal

Learn how to customize a Developer Portal and publish documentation using NGINX Management Suite API Connectivity Manager.


This documentation applies to NGINX Management Suite API Connectivity Manager 1.1.0 and later.

Overview

You can use NGINX Management Suite API Connectivity Manager (ACM) to create and manage Developer Portals (or, “Dev Portals”) to host your APIs and documentation. API Connectivity Manager Dev Portals provide a framework for customization that lets you match your Dev Portal to your brand’s or business' requirements. You can customize the Dev Portal website’s landing page, All APIs page, and Docs page(s), as well as the site’s header and footer.

Before You Begin

Complete the following prerequisites before proceeding with this guide:

  • ACM is installed, licensed, and running.
  • You have one or more Environments with a Developer Portal cluster.
  • You have verified that you can access the Developer Portal using the configured hostname.

How to Access the User Interface

This guide contains instructions for completing tasks by using the NGINX Management Suite API Connectivity Manager user interface (UI).

To access the UI, navigate to the FQDN for your NGINX Management Suite host and log in. Then, select “API Connectivity Manager” on the Launchpad menu.

Customize a Developer Portal

ACM uses a Dev Portal framework to define the look and feel of Developer Portals. These settings are applied at the Cluster level and apply to all Developer Portals hosted by the Cluster.

Take the steps below to customize your Dev Portal by defining a custom Dev Portal framework.

  1. In the ACM user interface, go to Environments > <your environment>, where “your environment” is the Environment that contains a Developer Portal Cluster.

  2. Select the desired Dev Portal Cluster from the Developer Portal Clusters list.

  3. In the Portal Design section, select Edit. You can then edit any of the options provided.

  4. You can save your changes at any time by selecting the Save and Publish option.

Note:

  • The Preview section to the right of the settings in each section will update automatically as you make changes.
  • The changes will be applied immediately when you select Save and Publish; as such we recommend testing any changes in a “non-production” Environment first.

Brand Options

  1. Select Upload Image.
  2. Browse your local filesystem and select the file you’d like to upload.
  3. Select Save and Publish or select Next to continue making changes.

Add a Favicon

  1. Select Upload Favicon.
  2. Browse your local filesystem and select the file you’d like to upload.
  3. Select Save and Publish or select Next to continue making changes.

Style Options

Colors

You can customize the colors of the following items:

  • page background,
  • page text,
  • theme (buttons, etc.), and
  • callouts (information, success, error, and warning).

To customize any of the above fields:

  1. Select the field that you want to customize.
  2. Enter the hex code for the desired color, or drag the sliders to create and refine a custom color.
  3. Select Save and Publish or select Next to continue making changes.

Fonts

You can customize the font used in any of the following:

  • hero text,
  • header and body text,
  • code.

To customize the font used in your Dev Portal(s):

  1. Select the field that you want to customize.
  2. Choose a font from the list provided.
  3. Select Save and Publish or select Next to continue making changes.

Website Options

You can customize the following sections of your Dev Portal website:

Header

You can customize the header’s background color, text color, and provide text to appear next to your logo image.

To customize the background or text color:

  1. Select the field that you want to customize.
  2. Enter the hex code for the desired color, or drag the sliders to create and refine a custom color.

To customize the header text, enter the text you want to use in the Complementary logo text field.

Then, select Save and Publish or select Next to continue making changes.

You can customize the footer’s background color, text color, and provide links to appear in the footer.

To customize the background or text color:

  1. Select the field that you want to customize.
  2. Enter the hex code for the desired color, or drag the sliders to create and refine a custom color.

To add links:

  1. Select Add Links.
  2. Provide the display text and the target URL.

To delete links:

  1. Select the “Delete” icon for any link that you want to remove.

Then, select Save and Publish or select Next to continue making changes.

Homepage

You can customize the following options for your Dev Portal homepage:

  • Hero image/banner text and color
  • “About Us” cards: The homepage features three cards, which appear below the banner.
  • Steps for getting started with your API.

To edit the hero image/banner:

  1. Select the Edit icon.
  2. Enter your desired text for the Title and Secondary Title.
  3. Select the Background field and/or Ink field, then enter the hex code for the desired color or drag the sliders to create and refine a custom color.
  4. Select Save Changes.

To edit the “About Us” cards:

  1. Select the Edit icon.
  2. Enter your desired Title (required), Description (required), icon, and Alt Text for each card.
  3. Select Save Changes.

To edit the Get Started steps:

  1. Select the Edit icon.
  2. Enter your desired Title (required), Description (required), icon, and Alt Text for each of the four steps.
  3. Select Save Changes.

At this point, we recommend selecting Save and Publish to save any customizations you’ve made. Verify that the changes have been applied, then move on to adding your Documentation.

Documentation

Configure Documentation Page

You can edit the Documentation Page section of your Dev Portal website to add custom documentation for your APIs. You can add or edit up to five Markdown documents. The following placeholder pages are included by default:

  • Get Started
  • Authentication
  • Responses
  • Errors

To customize the Documentation page of your Developer Portal, take the steps below:

  1. Select the Documentation option in the Edit Developer Portal sidebar.

  2. To add a new Markdown document, select Add Page. This adds a new blank item to the Pages table, which you can then edit and preview as described below.

    1. Select the Edit icon in the Pages table.
    2. Edit the sample text, or paste your text into the editor.
    3. Select Preview to view the Markdown rendered as HTML.
    4. Provide a new Page Name, if desired.
    5. Select Save to save your changes.
  3. To reorder your documents, select the up or down arrow next to the Page name.

When ready, select Save and Publish to save all of your changes and publish your documentation.

Configure All APIs Page

The All APIs page is where all of your APIs will appear on your Dev Portal site. To customize the Configure All APIs page of your Developer Portal, take the steps below:

  1. Select the Documentation option in the Edit Developer Portal sidebar.
  2. Select the Edit icon for the Configure All APIs section.
  3. Add your Page Description (required).
  4. Select Upload illustration to add a new full-width image to the page. Then, browse your local filesystem and select the file you’d like to upload.
  5. To change the image background color, select the Illustration Background field. Then, then enter the hex code for the desired color or drag the sliders to create and refine a custom color.
  6. Add the desired Alt Text for the image to the field provided.
  7. Select Save Changes.

When ready, select Save and Publish to save and publish your All APIs page changes.