DocsEdge StackDeveloper Portal
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.
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 Mapping
s
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 ofdocs.path
to theprefix
in theMapping
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 thisMapping
for documenting services. Note that the service will appear in the Dev Portal anyway if another, non-ignoredMapping
exists for the same service.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 adocs
attribute is specified. Users should setdocs.path
to/.ambassador-internal/openapi-docs
in theirMapping
s in order to keep the previous behavior.The
docs
field of Mappings was not introduced untilAmbassador Edge Stack
version 1.9 because Ambassador 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.
If you are on an earlier version of Ambassador, either upgrade to a newer version, or make your documentation available on
/.ambassador-internal/openapi-docs
.
Example:
With the Mapping
s 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.
Notes on access to documentation
path
s:By default, all the
path
s where documentation has been found will NOT be publicly exposed by the Ambassador Edge Stack. This is controlled by a specialFilterPolicy
installed internally.
Limitations on Mappings with a
host
attributeThe Dev Portal will ignore
Mapping
s that containhost
s that cannot be parsed as a valid hostname, or use a regular expression (whenhost_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 specificDevPortal
can be used as the default configuration by setting thedefault
attribute totrue
. Future versions will use otherDevPortals
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 filteringMapping
s:matchNamespaces
: list of namespaces, used for filtering theMapping
s that will be shown in theDevPortal
. When multiple namespaces are provided, theDevPortal
will considerMapping
s in any of those namespaces.matchLabels
: dictionary of labels, filtering theMapping
s that will be shown in theDevPortal
. When multiple labels are provided, theDevPortal
will only consider theMapping
s 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 aselector
).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 namespacedefault
will be displayed asdefault.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 prefixbackend
will be displayed asquote.backend
and its docs will have the relative path of/quote/backend
- "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 totrue
, the DevPortal will instead display the server definitions from theservers
section 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 searchableenabled
: 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
- When
type
: Configure the items fed into searchtitle-only
(default): only search over the names of DevPortal services and markdown pagesall-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 theDevPortal
. When you start publishing documentation for more services to yourDevPortal
, 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 yourDevPortal
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 contentbranch
: the Git branchdir
: 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
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 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
.
Setting | Description |
---|---|
AMBASSADOR_URL | External URL of Ambassador Edge Stack; include the protocol (e.g., https:// ) |
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 master ) |
DEVPORTAL_DOCS_BASE_PATH | Base path for api docs (defaults to /doc/ ) |
Visualize your API documentation in the cloud
If you haven't already done so, you may want to connect your cluster to Ambassador Cloud. Connected clusters will automatically report your Mapping
s' OpenAPI documents, allowing you to host and visualize all of your services API documentation on a shared, secure and authenticated platform.