Developer Portal API visualization is now available in Ambassador Cloud. These docs will remain as a historical reference for hosted Developer Portal installations. Go to the quick start guide.
The Dev Portal uses the
Mapping resource to automatically discover services known by
the Ambassador Edge Stack.
Mapping, the Dev Portal will attempt to fetch an OpenAPI V3 document
docs attribute is specified.
This documentation endpoint is defined by the optional
docs attribute in the
path: path for the OpenAPI V3 document. The Ambassador Edge Stack will append the value of
Mappingso 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
Mappingfor documenting services. Note that the service will appear in the Dev Portal anyway if another, non-ignored
Mappingexists for the same service.
display_name: custom name to show for this service in the devportal.
Previous versions of the Dev Portal tried to obtain documentation automatically from
/.ambassador-internal/openapi-docsby default, while the current version will not try to obtain documentation unless a
docsattribute is specified. Users should set
Mappings in order to keep the previous behavior.
docsfield of Mappings was not introduced until
Ambassador Edge Stackversion 1.9 because Ambassador was automatically searching for docs on
/.ambassador-internal/openapi-docsMake sure to update your CRDs with the following command if you are encountering problems after upgrading from an earlier version of Ambassador.
If you are on an earlier version of Ambassador, either upgrade to a newer version, or make your documentation available on
Mappings below, the Dev Portal would fetch OpenAPI documentation
service-a:5000 at the path
/srv/openapi/ and from
httpbin from an
service-b would have no documentation.
Notes on access to documentation
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
Limitations on Mappings with a
The Dev Portal will ignore
Mappings that contain
hosts that cannot be parsed as a valid hostname, or use a regular expression (when
All rendered API documentation is published at the
/docs/ URL by default. Users can
achieve a higher level of customization by creating a
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
DevPortalresources exist, the Dev Portal will pick a random one and ignore the rest. A specific
DevPortalcan be used as the default configuration by setting the
true. Future versions will use other
DevPortalsfor configuring alternative views of the Dev Portal.
DevPortal resources have the following syntax:
truewhen this is the default Dev Portal configuration.
content: see section below.
selector: rules for filtering
matchNamespaces: list of namespaces, used for filtering the
Mappings that will be shown in the
DevPortal. When multiple namespaces are provided, the
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
DevPortalwill 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
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
defaultwill be displayed as
default.quoteand its docs will have the relative path of
- "name.prefix" will display the docs with the name and prefix of the mapping.
e.g. a Mapping named
quotewith a prefix
backendwill be displayed as
quote.backendand its docs will have the relative path of
- "namespace.name" will display the docs with the namespace and name of the mapping. e.g. a Mapping named
preserve_servers: Configures the DevPortal to no longer dynamically build server definitions for the "try it out" request builder by using the Edge Stack hostname. When set to
true, the DevPortal will instead display the server definitions from the
serverssection of the Open API docs supplied to the DevPortal for the service.
search: as of Edge Stack 1.13.0, the DevPortal content is now searchable
enabled: default `false``; set to true to enable search functionality.
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.
The scope of the default Dev Portal can be restricted to
Mappings with the
public-api: true and
documented: true labels by creating
ambassador resource like this:
The Dev Portal can show a static list OpenAPI docs. In this example, a
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
The free and unlicensed versions of
Ambassador Edge Stackonly 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
DevPortalplease contact sales via our pricing information page.
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 Git repo specified in the optional
- the default repository at GitHub.
To use your own styling, clone or copy the repository, create an
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:
content can be have the following attributes:
url: Git URL for the content
branch: the Git branch
dir: subdirectory in the Git repo
Check out a local copy of your content repo and from within run the following docker image:
http://localhost:1080 in your browser. Any changes made locally to
devportal content will be reflected immediately on page refresh.
The docker command above will only work for AES versions 1.13.0+.
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:
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 Edge Stack setup.
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
With the above configuration, a mapping for
Will be displayed in the Dev Portal as
and the API documentation will be accessed at
You can also override the display name of documentation on a per-mapping basis.
Per-mapping overrides will take precedence over the
A mapping for
Will be displayed in the Dev Portal as
Cat Service, and the documentation will be
The Dev Portal supports some default configuration in some environment variables (for backwards compatibility).
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
|AMBASSADOR_URL||External URL of Ambassador Edge Stack; include the protocol (e.g., |
|POLL_EVERY_SECS||Interval for polling OpenAPI docs; default 60 seconds|
|DEVPORTAL_CONTENT_URL||Default URL to the repository hosting the content for the Portal|
|DEVPORTAL_CONTENT_DIR||Default content subdir (defaults to |
|DEVPORTAL_CONTENT_BRANCH||Default content branch (defaults to |
|DEVPORTAL_DOCS_BASE_PATH||Base path for api docs (defaults to |
If you haven't already done so, you may want to connect your cluster to Ambassador Cloud. Connected clusters will automatically report your
Mappings' OpenAPI documents, allowing you to host and visualize all of your services API documentation on a shared, secure and authenticated platform.