Swagger / OpenAPI Documentation

disaster-server includes Swagger / OpenAPI documentation support. It does not generate the contract ad hoc from Go handler comments. Instead, it reads a fixed OpenAPI contract file and exposes Swagger UI, OpenAPI YAML, and OpenAPI JSON when swagger.enabled=true.

This page explains how to enable, access, export, and maintain the API contract.

Enable Swagger

The server only registers documentation routes when Swagger is explicitly enabled:

swagger:
  enabled: true

The code default is disabled:

swagger.enabled=false

Production environments should keep Swagger disabled, or expose it only inside controlled networks, release validation environments, or test environments. Swagger routes are not mounted behind the business JWT middleware, so access control should be enforced by network boundaries, Ingress allowlists, gateway authentication, or environment isolation.

If deploying with Helm, ensure the disaster-server ConfigMap contains swagger.enabled=true, then restart the server Pod.

See Server Configuration for the current config-file location, local and Helm config sources, and the server.env, JWT, and license fields.

Endpoints

When enabled, server registers:

Path	Purpose
/swagger/	Swagger UI page. Open it in a browser.
/openapi.yaml	OpenAPI YAML contract.
/openapi.json	OpenAPI JSON contract converted from YAML.

Examples:

http://<server-host>:<server-port>/swagger/
http://<server-host>:<server-port>/openapi.yaml
http://<server-host>:<server-port>/openapi.json

Swagger UI loads /openapi.yaml from the same origin.

note

The current Swagger UI page uses CDN assets from swagger-ui-dist@5. If the deployment environment cannot access the public internet, /openapi.yaml and /openapi.json still work. For fully offline Swagger UI access, vendor the Swagger UI static assets locally or serve them through the gateway.

Contract Source

OpenAPI source file:

disaster-server/openspec/specs/disaster-server-openapi.yaml

Rules:

• The OpenAPI version is fixed to 3.0.3.
• Swagger UI, /openapi.yaml, /openapi.json, and release validation all read the same contract.
• Generated intermediate artifacts must not become the source of truth.
• Server API contract changes must update this file.

Export OpenAPI

From an environment that can access server:

curl -o disaster-server-openapi.yaml http://<server>/openapi.yaml
curl -o disaster-server-openapi.json http://<server>/openapi.json

The exported file can be imported into Postman, Apifox, Apipost, Swagger Editor, or other OpenAPI tools.

Local Validation

In the disaster-server repository:

go run ./tools/openapi validate \
  --spec openspec/specs/disaster-server-openapi.yaml

The same tool also provides routes, diff, and checklist subcommands for comparing server routes, RunAPI/Apipost inventory, and OpenAPI operations. The repository keeps related artifacts for release checks.

Documentation Site Strategy

The documentation site still keeps hand-written API docs for authentication, error codes, state machines, business semantics, and examples. Swagger/OpenAPI owns the machine-readable API contract, request/response fields, and schemas.

Generated reference pages can be introduced in two stages:

1. Keep hand-written API docs for business semantics, state machines, and examples.
2. Add a generation script to convert OpenAPI JSON/YAML into browsable API reference pages.

Candidates:

• Docusaurus OpenAPI plugin.
• Embedded Swagger UI as a standalone page.
• CI validation that checks OpenAPI consistency.

Release Acceptance Criteria

• In a validation environment with swagger.enabled=true, /swagger/ opens successfully.
• /openapi.yaml returns OpenAPI YAML.
• /openapi.json returns JSON converted from the same contract.
• go run ./tools/openapi validate --spec openspec/specs/disaster-server-openapi.yaml passes.
• New or changed APIs keep OpenAPI, hand-written API docs, error-code docs, and RunAPI/Apipost synchronized.
• OpenAPI examples must not include real tokens, kubeconfigs, AccessKeys, SecretKeys, licenses, or sensitive internal addresses.

Maintenance Rules

When changing server APIs, update:

• handler behavior.
• DTOs and request/response fields.
• OpenAPI spec.
• hand-written API docs.
• error codes and authentication semantics.

If the API drives operator behavior, also update operator CRD fields, status fields, and controller behavior documentation. Swagger describes the server's external API contract; it does not replace DR workflow, state-machine, or operations runbook documentation.