Developer Portal

Rendering API documentation

The Dev Portal uses the Mapping resource to automatically discover services known by the Ambassador Edge Stack.

For each Mapping, the Dev Portal will attempt to fetch an OpenAPI V3 document when a docs attribute is specified.

docs attribute in Mappings

This documentation endpoint is defined by the optional docs attribute in the Mapping.

where:

• path: path for the OpenAPI V3 document. The Ambassador Edge Stack will append the value of docs.path to the prefix in the Mapping so it will be able to use Envoy's routing capabilities for fetching the documentation from the upstream service . You will need to update your microservice to return a Swagger or OAPI document at this URL.
• url: absolute URL to an OpenAPI V3 document.
• ignored: ignore this Mapping for documenting services. Note that the service will appear in the Dev Portal anyway if another, non-ignored Mapping exists for the same service.
• timeout_ms: number of milliseconds that the devportal HTTP client will wait for a service to respond on their docs endpoint
• display_name: custom name to show for this service in the devportal.

Note:

Previous versions of the Dev Portal tried to obtain documentation automatically from /.ambassador-internal/openapi-docs by default, while the current version will not try to obtain documentation unless a docs attribute is specified. Users should set docs.path to /.ambassador-internal/openapi-docs in their Mappings in order to keep the previous behavior.

The docs field of Mappings was not introduced until Ambassador Edge Stack version 1.9 because Ambassador Edge Stack was automatically searching for docs on /.ambassador-internal/openapi-docs. Make sure to update your CRDs with the following command if you are encountering problems after upgrading from an earlier version of Ambassador Edge Stack.

If you are on an earlier version of Ambassador Edge Stack, either upgrade to a newer version, or make your documentation available on /.ambassador-internal/openapi-docs

Example:

With the Mappings below, the Dev Portal would fetch OpenAPI documentation from service-a:5000 at the path /srv/openapi/ and from httpbin from an external URL. service-b would have no documentation. The httpbin service must respond in 4000 seconds or else the request will time out.

Notes on access to documentation paths:

By default, all the paths where documentation has been found will NOT be publicly exposed by the Ambassador Edge Stack. This is controlled by a special FilterPolicy installed internally.

Limitations on Mappings with a host attribute

The Dev Portal will ignore Mappings that contain hosts that cannot be parsed as a valid hostname, or use a regular expression (when host_regex: true).

Publishing the documentation

All rendered API documentation is published at the /docs/ URL by default. Users can achieve a higher level of customization by creating a DevPortal resource. DevPortal resources allow the customization of:

• what documentation is published
• how it looks

Users can create a DevPortal resource for specifying the default configuration for the Dev Portal, filtering Mappings and namespaces and specifying the content.

Note: when several DevPortal resources exist, the Dev Portal will pick a random one and ignore the rest. A specific DevPortal can be used as the default configuration by setting the default attribute to true. Future versions will use other DevPortals for configuring alternative views of the Dev Portal.

DevPortal resources have the following syntax:

where:

• default: true when this is the default Dev Portal configuration.
• content: see section below.
• selector: rules for filtering Mappings:
  • matchNamespaces: list of namespaces, used for filtering the Mappings that will be shown in the DevPortal. When multiple namespaces are provided, the DevPortal will consider Mappings in any of those namespaces.
  • matchLabels: dictionary of labels, filtering the Mappings that will be shown in the DevPortal. When multiple labels are provided, the DevPortal will only consider the Mappings that match all the labels.
• docs: static list of service/documentation pairs that will be shown in the Dev Portal. Only the documentation from this list will be shown in the Dev Portal (unless additional docs are included with a selector).
  • service: service name used for listing user-provided documentation.
  • url: a full URL to a OpenAPI document for this service. This document will be served as it is, with no extra processing from the Dev Portal (besides replacing the hostname).
• naming_scheme: Configures how DevPortal docs are displayed and linked to in the UI.
  • "namespace.name" will display the docs with the namespace and name of the mapping. e.g. a Mapping named quote in namespace default will be displayed as default.quote and its docs will have the relative path of /default/quote
  • "name.prefix" will display the docs with the name and prefix of the mapping. e.g. a Mapping named quote with a prefix backend will be displayed as quote.backend and its docs will have the relative path of /quote/backend
• search: as of Ambassador Edge Stack 1.13.0, the DevPortal content is now searchable
  • enabled: default `false``; set to true to enable search functionality.
    • When enabled=false, the DevPortal search endpoint (/[DEVPORTAL_PATH/api/search) will return an empty response
  • type: Configure the items fed into search
    • title-only (default): only search over the names of DevPortal services and markdown pages
    • all-content: Search over openapi spec content and markdown page content.

Example:

The scope of the default Dev Portal can be restricted to Mappings with the public-api: true and documented: true labels by creating a DevPortal ambassador resource like this:

Example:

The Dev Portal can show a static list OpenAPI docs. In this example, a eks.aws-demo service is shown with the documentation obtained from a URL. In addition, the Dev Portal will show documentation for all the services discovered in the aws-demo namespace:

Note:

The free and unlicensed versions of Ambassador Edge Stack only support documentation for five services in the DevPortal. When you start publishing documentation for more services to your DevPortal, keep in mind that you will not see more than 5 OpenAPI documents even if you have more than 5 services properly configured to report their OpenAPI specifications. For more information on extending the number of services in your DevPortal please contact sales via our pricing information page.

Styling the DevPortal

The look and feel of a DevPortal can be fully customized for your particular organization by specifying a different content, customizing not only what is shown but how it is shown, and giving the possibility to add some specific content on your API documentation (e.g., best practices, usage tips, etc.) depending on where it has been published.

The default Dev Portal content is loaded in order from:

• the ambassador DevPortal resource.
• the Git repo specified in the optional DEVPORTAL_CONTENT_URL environment variable.
• the default repository at GitHub.

To use your own styling, clone or copy the repository, create an ambassador DevPortal and update the content attribute to point to the repository. If you wish to use a private GitHub repository, create a Personal Access Token and include it in the content following the example below:

The content can be have the following attributes:

where:

• url: Git URL for the content
• branch: the Git branch
• dir: subdirectory in the Git repo

Iterating on Dev Portal styling and content

Local Development

Check out a local copy of your content repo and from within run the following docker image:

and open http://localhost:1080 in your browser. Any changes made locally to devportal content will be reflected immediately on page refresh.

Note:

The docker command above will only work for AES versions 1.13.0+.

Remote Ambassador Edge Stack

After committing and pushing changes to your devportal content repo changes to git, set your DevPortal to fetch from your branch:

Then you can force a reload of DevPortal content by hitting a refresh endpoint on your remote ambassador:

Note:

The DevPortal does not share a cache between replicas, so the content refresh endpoint will only refresh the content on a single replica. It is suggested that you use this endpoint in a single replica Ambassador Edge Stack setup.

Customizing documentation names and paths

The Dev Portal displays the documentation's Mapping name and namespace by default, but you can override this behavior.

To change the documentation naming scheme for the entire Dev Portal, you can set naming_scheme in the DevPortal resource:

With the above configuration, a mapping for service-a:

Will be displayed in the Dev Portal as service-a.path, and the API documentation will be accessed at $AMBASSADOR_URL/docs/doc/service-a/path.

You can also override the display name of documentation on a per-mapping basis. Per-mapping overrides will take precedence over the DevPortal naming_scheme.

A mapping for service-b with display_name set:

Will be displayed in the Dev Portal as Cat Service, and the documentation will be accessed at $AMBASSADOR_URL/docs/doc/Cat%20Service.

Default configuration

The Dev Portal supports some default configuration in some environment variables (for backwards compatibility).

Environment variables

The Dev Portal can also obtain some default configuration from environment variables defined in the AES Deployment. This configuration method is considered deprecated and kept only for backwards compatibility: users should configure the default values with the ambassador DevPortal.