zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
2.6 KiB
Example Endpoint
Endpoints will be formatted like this. - These are not real endpoints!
Greet a user.
GET /api/v1/greet
This endpoint greets the user.
Permissions
If permissions are required, they will be listed here.
- example_permission
Parameters
Parameters are required unless explicitly stated to be optional.
!!! note
As mentioned in API Overview, GET parameters are to be sent in the query string,
and all other methods are to have their content in the request body as
application/json.
| Property | Type | Description |
|---|---|---|
name |
String | The name of the user to greet. |
birthday (optional) |
Presence | Whether it is the user's birthday or not. |
Not providing required parameters will result in a 400 error.
Response
Parameters are always present unless stated to be conditional/optional.
!!! info
The below properties correspond to keys in the body
property of a request.
This means that the below table corresponds to
```json
{
"success": true,
"description": "Greeted user.",
"body": {
"greeting": "Hello, zkldi!",
"wasBirthday": false,
}
}
```
| Property | Type | Description |
|---|---|---|
greeting |
String | A greeting for the user. |
wasBirthday |
Boolean | Whether today is the users birthday or not. |
!!! info
Since the above table corresponds to keys in the body
property of a request, the special property name
<body> refers to the body itself.
For example:
| Property | Type | Description |
| :: | :: | :: |
| `<body>` | String | The greeting. |
Corresponds to:
```json
{
"success": true,
"description": "Greeted user.",
"body": "Hello, zkldi
}
```
Example
Request
GET /greet?name=zkldi
Response
{
"greeting": "Hello, zkldi
"wasBirthday": false
}
!!! warning
The example response is implicitly the body key of the API response.
That is to say that, the real response for this request is:
```json
{
"success": true,
"description": "Greeted user.",
"body": {
"greeting": "Hello, zkldi
"wasBirthday": false
}
}
```
This is omitted, because it's redundant all of the time. -- That is to say,
You should never depend on parsing the content of `description`.