83 lines
3.6 KiB
Markdown
83 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"name": "switch-01",
|
|
"device_type": "switchos",
|
|
"host": "192.0.2.10",
|
|
"port": 80,
|
|
"use_global_switchos_credentials": true
|
|
}
|
|
```
|
|
|
|
Update only the binary backup schedule:
|
|
|
|
```json
|
|
{
|
|
"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](https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md),
|
|
[configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/),
|
|
[swagger-ui-dist package](https://registry.npmjs.org/swagger-ui-dist/5.34.0).
|
|
|
|
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.
|