46 lines
1.9 KiB
Rust
46 lines
1.9 KiB
Rust
|
/// A single query/path/body parameter declared on an API route.
|
||
|
|
#[derive(serde::Serialize, Clone)]
|
||
|
|
pub struct ApiParam {
|
||
|
|
pub name: &'static str,
|
||
|
|
/// Rust-like type hint: string | u32 | bool | i64 | json.
|
||
|
|
pub kind: &'static str,
|
||
|
|
/// "required" | "optional" | "default=<value>"
|
||
|
|
pub constraint: &'static str,
|
||
|
|
pub description: &'static str,
|
||
|
|
}
|
||
|
|
|
||
|
|
/// Static metadata for an HTTP endpoint.
|
||
|
|
///
|
||
|
|
/// Registered at link time via [`inventory::submit!`] — generated by
|
||
|
|
/// `#[onto_api(...)]` proc-macro attribute on each handler function.
|
||
|
|
/// Collected via [`inventory::iter::<ApiRouteEntry>()`].
|
||
|
|
#[derive(serde::Serialize, Clone)]
|
||
|
|
pub struct ApiRouteEntry {
|
||
|
|
pub method: &'static str,
|
||
|
|
pub path: &'static str,
|
||
|
|
pub description: &'static str,
|
||
|
|
/// Authentication required: "none" | "viewer" | "bearer" | "admin"
|
||
|
|
pub auth: &'static str,
|
||
|
|
/// Which actors typically call this endpoint.
|
||
|
|
pub actors: &'static [&'static str],
|
||
|
|
pub params: &'static [ApiParam],
|
||
|
|
/// Semantic grouping tags (e.g. "graph", "federation", "describe").
|
||
|
|
pub tags: &'static [&'static str],
|
||
|
|
/// Non-empty when the endpoint is only compiled under a feature flag.
|
||
|
|
pub feature: &'static str,
|
||
|
|
}
|
||
|
|
|
||
|
|
inventory::collect!(ApiRouteEntry);
|
||
|
|
|
||
|
|
/// Serialize all statically-registered [`ApiRouteEntry`] items to a
|
||
|
|
/// pretty-printed JSON array, sorted by path then method.
|
||
|
|
///
|
||
|
|
/// Intended for daemon binaries that expose a `--dump-api-catalog` flag: write
|
||
|
|
/// the output to `api-catalog.json` in the project root so the ontoref UI can
|
||
|
|
/// display the API surface of consumer projects that run as separate processes.
|
||
|
|
pub fn dump_catalog_json() -> String {
|
||
|
|
let mut routes: Vec<&'static ApiRouteEntry> = inventory::iter::<ApiRouteEntry>().collect();
|
||
|
|
routes.sort_by(|a, b| a.path.cmp(b.path).then(a.method.cmp(b.method)));
|
||
|
|
serde_json::to_string_pretty(&routes).unwrap_or_else(|_| "[]".to_string())
|
||
|
|
}
|