evalhub_schema/openapi.rs
1//! The hand-written skeleton of the OpenAPI 3.1 document.
2//!
3//! Almost all of `openapi.json` is derived: the record and query schemas come
4//! from the `JsonSchema` derives in this crate, and the paths come from the
5//! handlers in `evalhub_server`, described through `aide`. What is not
6//! derivable — `info`, `servers`, the security scheme, the shared `422` /
7//! `409` / `404` responses that reference [`crate::error`] — is assembled
8//! here so that the server only has to merge it.
9//!
10//! OpenAPI 3.1 was chosen over 3.0 because 3.1's schema dialect *is* JSON
11//! Schema 2020-12. The schema a client fetches from `GET /schemas/card` and
12//! the one embedded in `openapi.json` are byte-identical; with 3.0 they
13//! could not be.
14//!
15//! The document is served at `GET /openapi.json` and snapshot-tested in the
16//! server crate. A change to a handler that changes the document is not done
17//! until the snapshot has been updated in the same commit and the `web/`
18//! client regenerated in the same pull request.
19//!
20//! This crate does not depend on an OpenAPI library; it exposes the
21//! constants and the server builds the `Info` object from them.
22
23/// `info.title` of the served document.
24pub const TITLE: &str = "evalhub";
25
26/// `info.description` of the served document.
27pub const DESCRIPTION: &str = "A hosting service for named, versioned LLM evaluation results (Cards) \
28and their materials (Evals). The hub validates, indexes and compares; it does not run evaluations.";
29
30/// The API's version, as carried in `info.version`. Independent of the crate
31/// version: it changes when the contract changes.
32pub const API_VERSION: &str = "1.0.0";
33
34/// Path prefix of every API route.
35pub const API_PREFIX: &str = "/api/v1";