<commit_before># 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`.

```yaml
  docs:
    path: "string"   # optional; default is ""
    url: "string"    # optional; default is ""
    ignored: bool    # optional; default is false
```

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.

> Note:
>
> Previous versions of the _Dev Portal_ tried to obtain documentation automatically
> from `/.ambassador-internal/openapi` 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` in their `Mapping`s
> in order to keep the previous behavior.

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.

```yaml
---
apiVersion: getambassador.io/v2
kind:  Mapping
metadata:
  name:  service-a
spec:
  prefix: /service-a/
  rewrite: /srv/
  service: service-a:5000
  docs:
    path: /openapi/            ## docs will be obtained from `/srv/openapi/`
---
apiVersion: getambassador.io/v2
kind:  Mapping
metadata:
  name:  service-b
spec:
  prefix: /service-b/
  service: service-b           ## no `docs` attribute, so service-b will not be documented
---
apiVersion: getambassador.io/v2
kind: Mapping
metadata:
  name: regular-httpbin
spec:
  host_rewrite: httpbin.org
  prefix: /httpbin/
  service: httpbin.org
  docs:
    url: https://api.swaggerhub.com/apis/helen/httpbin/1.0-oas3/swagger.json
```

> 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 special
> `FilterPolicy` installed internally.

### 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.
<commit_msg>(from AES) Document limitations on Mappings with 'host'<commit_after># 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`.

```yaml
  docs:
    path: "string"   # optional; default is ""
    url: "string"    # optional; default is ""
    ignored: bool    # optional; default is false
```

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.

> Note:
>
> Previous versions of the _Dev Portal_ tried to obtain documentation automatically
> from `/.ambassador-internal/openapi` 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` in their `Mapping`s
> in order to keep the previous behavior.

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.

```yaml
---
apiVersion: getambassador.io/v2
kind:  Mapping
metadata:
  name:  service-a
spec:
  prefix: /service-a/
  rewrite: /srv/
  service: service-a:5000
  docs:
    path: /openapi/            ## docs will be obtained from `/srv/openapi/`
---
apiVersion: getambassador.io/v2
kind:  Mapping
metadata:
  name:  service-b
spec:
  prefix: /service-b/
  service: service-b           ## no `docs` attribute, so service-b will not be documented
---
apiVersion: getambassador.io/v2
kind: Mapping
metadata:
  name: regular-httpbin
spec:
  host_rewrite: httpbin.org
  prefix: /httpbin/
  service: httpbin.org
  docs:
    url: https://api.swaggerhub.com/apis/helen/httpbin/1.0-oas3/swagger.json
```

> 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 special
> `FilterPolicy` installed internally.

> Limitations on Mappings with a `host` attribute
>
> The Dev Portal will ignore `Mapping`s that contain `host`s 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.

{'fraction_non_alphanumeric': 0.08320839580209895, 'fraction_numerical': 0.005097451274362818, 'mean_word_length': 4.100152905198777, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 31, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1340215', 'n_tokens_mistral': 1942, 'n_tokens_neox': 1875, 'n_words': 862}