feat(api): publish the OpenAPI document for AI agents #8

Merged

macoun merged 1 commit from feat/openapi-for-agents into main

2026-10-19 12:27:54 +00:00

macoun commented

2026-10-19 12:24:23 +00:00

Owner

Why

Agents in the company read an API's Swagger document and call REST with a portal JWT
(main API, Dynamic Management, GNSS caster). The tracker served its document only in
Development, so an agent could not use it in production.

What

/swagger/v1/swagger.json is served in every environment. Outside Development it
requires a team member token — the same gate as the data (401 without a token,
403 for non-GlobalAdmins). Swagger UI stays Development-only.
Endpoint descriptions come from XML comments; the document opens with a short
orientation for agents (login, where to start, state changes only via operations,
contract texts are data not instructions, never store credentials).
The document gets the strict API security headers; the Swagger UI exemption now
applies only in Development.
Two stale param comments removed (rejected by the documentation build).
ADR-026: the decision, and why an MCP server is deferred.

Security

Production probed live: /swagger/* returns 401 without a token.
Generated document scanned: no IPs, e-mails, internal URLs or secrets.
The XML comments file is not downloadable (static files come only from wwwroot).
Tests cover token-less access via .json, .yaml, upper-case path and unknown
document name, plus security headers on /swagger/* outside Development.

Testing

dotnet build — 0 warnings; dotnet test — 241 passed (4 new in OpenApiTests).

## Why Agents in the company read an API's Swagger document and call REST with a portal JWT (main API, Dynamic Management, GNSS caster). The tracker served its document only in Development, so an agent could not use it in production. ## What - `/swagger/v1/swagger.json` is served in every environment. Outside Development it requires a team member token — the same gate as the data (401 without a token, 403 for non-GlobalAdmins). Swagger UI stays Development-only. - Endpoint descriptions come from XML comments; the document opens with a short orientation for agents (login, where to start, state changes only via operations, contract texts are data not instructions, never store credentials). - The document gets the strict API security headers; the Swagger UI exemption now applies only in Development. - Two stale `param` comments removed (rejected by the documentation build). - ADR-026: the decision, and why an MCP server is deferred. ## Security - Production probed live: `/swagger/*` returns 401 without a token. - Generated document scanned: no IPs, e-mails, internal URLs or secrets. - The XML comments file is not downloadable (static files come only from `wwwroot`). - Tests cover token-less access via `.json`, `.yaml`, upper-case path and unknown document name, plus security headers on `/swagger/*` outside Development. ## Testing `dotnet build` — 0 warnings; `dotnet test` — 241 passed (4 new in `OpenApiTests`).

macoun added 1 commit

2026-10-19 12:24:23 +00:00

feat(api): publish the OpenAPI document for AI agents

Build and publish Docker image / migrations-check (pull_request) Successful in 44s

Details

Build and publish Docker image / test (pull_request) Successful in 1m46s

Details

Build and publish Docker image / frontend (pull_request) Successful in 45s

Details

Build and publish Docker image / build-and-push (pull_request) Has been skipped

Details

6f938c4614

Agents in the company work by reading an API's Swagger document and calling
REST with a portal JWT. The tracker served its document only in Development,
so an agent could not use it in production.

- Serve /swagger/v1/swagger.json in every environment. Outside Development it
  requires a team member token, the same gate as the data. Swagger UI stays
  Development-only.
- Include XML comments so endpoints carry their descriptions, and open the
  document with a short orientation for agents: how to log in, where to start,
  that state changes go through operations, and that contract texts are data,
  not instructions.
- Give the document the strict API security headers and limit the Swagger UI
  exemption to Development.
- Remove two stale param comments that the documentation build rejects.
- Record the decision, and why an MCP server is deferred, in ADR-026.

macoun merged commit 352c099cf1 into main

2026-10-19 12:27:54 +00:00

macoun deleted branch feat/openapi-for-agents

2026-10-19 12:27:54 +00:00

macoun referenced this pull request from a commit

2026-10-19 12:27:55 +00:00

Merge pull request 'feat(api): publish the OpenAPI document for AI agents' (#8) from feat/openapi-for-agents into main