Brian Refsdal
171f597d4e
## Description
Adds public documentation for `GET /v2/auditlogs/governance/{org_name}`
and aligns the guide and OpenAPI reference with merged data-platform
main (`66bc70971`), including
[docker/data-platform#2711](https://github.com/docker/data-platform/pull/2711)
and
[docker/data-platform#2712](https://github.com/docker/data-platform/pull/2712).
- Documents raw Organization Access Token authentication and the View
audit logs permission.
- Covers the 25-event default, 100-event page cap, 30-day request
window, and cursor-preserved time bounds. Text search can use the
default window.
- Documents the API and gateway organization limits of 5 requests per
second and the gateway limit of 600 requests per minute per source IP.
Clients and tokens share the organization limits, and each pagination
request counts.
- Updates the structured application 429 example to `limit: 5`,
`window_seconds: 1`, and `retry_after_seconds: 1`.
- Keeps Retry-After optional: application responses include it when the
reset time is known, while gateway responses can omit it and use a
different body. The chart-owned Lua policy was removed in
[docker/data-platform#2725](https://github.com/docker/data-platform/pull/2725);
these docs do not promise gateway header translation.
- Covers request deadlines, search timeouts, and retryable dependency
failures, with links to the audit record reference and
subscription/access-token pages.
## Release status
The production route and gateway policies are enabled in the merged
configuration. One unauthenticated GET to
`https://api.docker.com/v2/auditlogs/governance/vonwig?page_size=1`
returned HTTP 401 with `{"error":"missing or malformed Authorization
header"}`, confirming public routing and missing-token rejection.
Before publishing, confirm the OAT View audit logs permission is
available in Docker Home and record authorized production
query/pagination, organization/IP throttling, retry behavior, and
monitoring validation. No authenticated request or rate-limit load test
was performed in this update. Merged configuration and a 401 response do
not establish those outcomes.
## Validation
- Scoped rumdl and Vale checks: passed with 0 errors, warnings, or
suggestions.
- Prettier check for the OpenAPI YAML: passed.
- OpenAPI 3.0 validation: passed using @apidevtools/swagger-parser
10.1.0.
- Public server and application 429 example checked against the merged
production values.
- `git diff --check`: passed.
- Full Hugo rendering and rendered link validation were not run; PR CI
and the deploy preview still need review.
API reference build
This tool validates the Hub, DVP, Registry, AI Governance, and Sandboxes OpenAPI sources
in content/reference/api/ and generates presentation data for Hugo. Engine
retains its existing sources and renderer.
Commands
Site builds use the committed data/api-reference.json. To build the site,
use Hugo and the site's Node dependencies. From the repository root:
$ npm ci
$ hugo server
For a static build with HTML/Markdown checks, run
./hack/api-docs/run.sh build. To serve that build on port 1314, run
./hack/api-docs/run.sh serve. Set DOCS_URL and DOCS_PORT when using another
address. These commands use the committed data without running the generator.
After changing a specification, source manifest entry, or generator code, use
the Go version declared in hack/api-docs/go.mod to regenerate the data.
Install the Vacuum version pinned in the Dockerfile and make
the vacuum executable available on PATH. The script runs Vacuum and the Go
generator without installing tools.
$ ./hack/api-docs/run.sh test
$ ./hack/api-docs/run.sh generate
Commit data/api-reference.json with the source changes. With
docker compose watch, the regenerated JSON syncs to the server and Hugo
rebuilds the reference. Docker builds and Netlify deploy previews also use the
committed JSON. Validation reports and local builds remain under
tmp/api-reference/.
Processor inputs
sources.json registers input specifications and their product/manual
relationships. Both generation and the validation wrapper use this manifest.
Hugo reads the generated presentation data, rather than this file. Authentication
descriptions come from the specifications and linked guides.
validation/ contains the Vacuum rules and locked official
schema resources. testdata/ contains validation fixtures. The presentation model
version and supported dialect are defined by the processor, not configurable
manifest fields.
Pipeline
- Parse the authoritative YAML with
libopenapiand preserve source values and reference identities. Verify locked OpenAPI dialect resources. - Run Vacuum policy checks and JSON Schema validation of schemas and supplied examples, followed by documentation profile checks.
- Generate presentation model version 1: operations, effective security and servers, parameters, media variants, examples, schema links, and provenance.
- Render HTML and Markdown through the content adapter and
api-docstemplates. - Run the shared site flattening script, then check generated operation, parameter, media, schema, and link coverage.
The shared hack/flatten-and-resolve.js script resolves Markdown link destinations
relative to each original file, then moves index.md files to flattened paths.
It preserves code examples and other text. API pages use the same processing as
other pages; links that already use published URLs remain unchanged.
The published YAML URLs still serve the source files directly.
Validation
check is strict and reports every documentation profile failure:
$ ./hack/api-docs/run.sh check
Generation runs the same strict validation. Any diagnostic fails generation;
there is no exception baseline. Reports are written to
tmp/api-reference/validation.json.
The build workflow's validation matrix runs API reference checks alongside the other validation targets. It runs tests, validates the sources, regenerates the JSON, and compares the result with the committed file to detect stale data. This matrix entry is advisory: failures do not block site builds or deployment.
Run the same check locally with Docker:
$ docker buildx bake validate-api-reference
This target runs generator tests, strict validation, and a byte-for-byte
comparison inside Docker. It leaves the working tree unchanged and is also
included in the validate Bake group.
Tests and scope
Go fixtures cover dialects, references, recursion, boolean schemas, examples,
security overrides, server and parameter precedence, and request generation.
verify-output.mjs checks all generated HTML/Markdown pairs, retention of
Engine v1.40–v1.56 in ReDoc, and byte-identical published specifications. It
also checks local links and fragments from API pages, including links to
docs.docker.com. The site htmltest checks include migrated Hub, DVP,
Registry, and AI Governance references. browser-checks.mjs exports a
Playwright check for navigation, page aliases, filtering, requests, and narrow
screens.
Callbacks and webhook navigation are unsupported and fail validation. Request examples are POSIX shell templates; they do not make service calls.
Examples are optional. Supplied examples must validate against their schemas.
When a request body has no example, the generated cURL command reads from
request-body and directs the reader to prepare that file from the schema.