mirror of
https://github.com/zkldi/Tachi.git
synced 2026-09-26 17:07:58 +03:00
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
114 lines
2.6 KiB
Markdown
114 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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`.
|