`redocly.apigee`

Plans:Enterprise

Use the redocly.apigee option to configure the Apigee developer onboarding plugin: the Apigee organization it connects to, the page where developers get API keys, approvals, the API products developers can request, and teams.

The plugin needs version 1.0.0-next.0 or later of the @redocly/framework package. Add the plugin to plugins and set its configuration in redocly.apigee, the plugin ID. The plugin connects to one Apigee organization. The build checks the options: it shows an error for an option with a wrong value and a warning for an option that the plugin does not know.

The plugin requires a plan that includes developer onboarding. Without it, the plugin doesn't add pages and the build displays a warning.

Options

Option	Type	Description
organizationName	string	REQUIRED. Name of the Apigee organization. Example: `museum-prod`.
auth	Apigee auth object	REQUIRED. Authentication for the Apigee management API.
apiUrl	string	URL to send Apigee management API requests to, for example through a proxy. Default: `https://apigee.googleapis.com/v1`.
stage	string	Mark the Apigee organization as production or non-production in the UI. Default: `non-production`.
title	string	Name of the page with the developer's apps, and of the link to it next to the user menu. Default: `API keys`.
basePath	string	Path of the page with the developer's apps, starting with `/`. Default: `/apps`.
approvals	Approvals object	The Approvals page, for API products that require approval.
apiProducts	API products object	The API products developers can request.
teams	Teams object	Teams that share apps.

Approvals object

Option	Type	Description
enabled	boolean	Serve the Approvals page and its routes. Reviewers come from `rbac` roles. Default: `false`.

API products object

Option	Type	Description
include	[string]	A list of API products that are offered. Default: every product of the organization.
exclude	[string]	A list of API products that are never offered.
allowOutsideCatalog	boolean	Offer products that no API page in the project documents. Default: `false`. A product is then offered only when an API description names it in `x-metadata.apiId` and the developer can open that page.
matchByTitle	boolean	Also match a product to the API page whose title equals the product's display name, for projects that don't name products in their API descriptions. An `apiId` always wins. Default: `false`.

Teams object

Option	Type	Description
enabled	boolean	Let developers create teams and share apps. Teams use Apigee app groups, which Apigee Edge doesn't have. Default: `false`.

Examples

The following configuration names the page Developer keys, serves it at /developers/apps, turns on approvals, and never offers the internal-billing product:

redocly.yaml

plugins:
  - '@redocly/framework-plugin-apigee/plugin.js'
redocly.apigee:
  organizationName: museum-prod
  auth:
    type: SERVICE_ACCOUNT
    serviceAccountEmail: portal@museum-prod.iam.gserviceaccount.com
    serviceAccountPrivateKey: '{{ process.env.APIGEE_PRIVATE_KEY }}'
  title: Developer keys
  basePath: /developers/apps
  approvals:
    enabled: true
  apiProducts:
    exclude:
      - internal-billing

Migrate from `developerOnboarding`

A classic Realm project connects to Apigee with an adapter in developerOnboarding. Framework reads the first Apigee adapter there as redocly.apigee and displays a warning. The adapter keeps working once you add the plugin. A redocly.apigee option you set wins, and other Apigee adapters are ignored.

To move the adapter, copy organizationName, auth, apiUrl, and stage to redocly.apigee, and drop type. The product options move into apiProducts:

ignoreApiProducts becomes apiProducts.exclude.
allowApiProductsOutsideCatalog becomes apiProducts.allowOutsideCatalog.

Resources

Add developer onboarding with Apigee - Install the Apigee plugin and connect API reference pages to API products
developerOnboarding - The classic Realm adapters and the Apigee auth objects
rbac - Give teams the roles that review access requests

redocly.apigee