mikrotik-backup/docs/api-documentation.md

Interactive API documentation — 0.0.1

URLs

URL	Content
/docs, /docs/	Local Swagger UI with the complete contract and request execution
/openapi.json	OpenAPI 3.1.0 with 36 operations and input/output models
/redoc	Compatibility redirect to /docs

The default API base path is /api. The server applies the configured API_PREFIX to servers and the OAuth2 login URL, and includes the application name and version in the document metadata. Changing the prefix requires no JSON edits.

Authentication and examples

In the Authorize dialog, select one authentication method:

• OAuth2PasswordBearer: the username and password of an existing account. The documentation submits a form to /api/auth/login and uses the returned token.
• BearerAuth: the access_token value, without the Bearer prefix.

For an operation, select Try it out, fill in the fields, and select Execute. Requests perform real operations on the current instance. Updates, outgoing messages, backups, and deletions use the same permissions and limits as the application interface. Registration requires an explicit ALLOW_REGISTRATION=true.

Add a SwitchOS device using the global username/password pair:

{
  "name": "switch-01",
  "device_type": "switchos",
  "host": "192.0.2.10",
  "port": 80,
  "use_global_switchos_credentials": true
}

Update only the binary backup schedule:

{
  "binary_cron": "0 2 * * *"
}

Omitted fields remain unchanged. Empty or null secret fields preserve stored values; explicit clear_* flags remove them. Public responses do not expose stored passwords or keys. A separate endpoint reveals the global SSH key after the account password is entered again.

Assets and maintenance

docs/openapi.json is the contract template. src/api/documentation.rs serves it with the current instance configuration. The HTML, initializer, stylesheet, and local Swagger UI distribution are embedded directly from the checked-in source files at compile time. On first use, the application combines the embedded assets into one docs.js and one docs.css. Their URLs contain content hashes for browser caching. Documentation assets do not depend on generated files in OUT_DIR; build.rs builds only the main application assets.

The official swagger-ui-dist 5.34.0 distribution is pinned and was downloaded from its publisher registry. The archive SHA-512 was checked against the published integrity value. Original assets, the Apache-2.0 license, NOTICE, and bundled library licenses are in vendor/swagger-ui/. Source details and individual file checksums are recorded in vendor/swagger-ui/PROVENANCE.json.

Upstream sources: Swagger UI installation, configuration, swagger-ui-dist package.

The remote validator, query-string configuration, and persistent browser token storage are disabled. The request interceptor permits only same-origin requests; the Content Security Policy disallows external scripts. Building and running the documentation requires neither Node nor a CDN connection.

tests/openapi_contract.rs checks every documented method and path against the actual Axum router, authentication requirements, local schema references, a custom API prefix, English documentation, and embedded assets. It also checks that the cache keys in the HTML match the served asset contents. Browser testing covers rendering and request execution on an isolated instance.