first commit

docs/api-documentation.md

@@ -0,0 +1,82 @@
+# 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.