cognee_http_server/
openapi.rs

1//! OpenAPI document assembly via `utoipa`.
2//!
3//! `ApiDoc` is the root `OpenApi` struct.  Routers register their paths into
4//! it via `utoipa-axum` in their respective phases.  For P0 the `paths` list is
5//! empty; the document itself (title, version, security schemes) is wired here.
6//!
7//! `openapi_json` is the handler registered at `GET /openapi.json`.
8
9use axum::{Json, response::IntoResponse};
10use utoipa::{
11    Modify, OpenApi,
12    openapi::{
13        Components,
14        security::{ApiKey, ApiKeyValue, HttpAuthScheme, HttpBuilder, SecurityScheme},
15    },
16};
17
18/// Root OpenAPI document.
19///
20/// Security schemes mirror Python's `custom_openapi()` from
21/// [`client.py:126-162`](https://github.com/topoteretes/cognee/blob/main/cognee/api/client.py#L126-L162).
22#[derive(OpenApi)]
23#[openapi(
24    info(
25        title = "Cognee API",
26        version = "1.0.0",
27        description = "Cognee HTTP API — Rust port of the Python FastAPI server."
28    ),
29    modifiers(&SecurityAddon),
30    paths(
31        // E-02 — typed-entry remember
32        crate::routers::remember::post_remember_entry,
33        // P4 read-path handlers
34        crate::routers::search::get_search_history,
35        crate::routers::search::post_search,
36        crate::routers::recall::get_recall_history,
37        crate::routers::recall::post_recall,
38        // E-09 — sessions list
39        crate::routers::sessions::list_sessions,
40        // E-10 — sessions stats
41        crate::routers::sessions::get_stats,
42        // E-11 — sessions cost-by-model
43        crate::routers::sessions::cost_by_model,
44        // E-12 — sessions detail
45        crate::routers::sessions::get_session_detail,
46        crate::routers::llm::post_custom_prompt,
47        crate::routers::llm::post_infer_schema,
48        crate::routers::visualize::get_visualize,
49        crate::routers::visualize::post_visualize_multi,
50        // P5 admin handlers (settings stays OSS; configuration +
51        // the permissions/users/auth/api-keys families moved to the
52        // closed `cognee-http-cloud` crate, which publishes its own
53        // OpenAPI overlay).
54        crate::routers::settings::get_settings,
55        crate::routers::settings::save_settings,
56        // P7 notebooks + responses
57        crate::routers::notebooks::list_notebooks,
58        crate::routers::notebooks::create_notebook,
59        crate::routers::notebooks::update_notebook,
60        crate::routers::notebooks::delete_notebook,
61        crate::routers::notebooks::run_notebook_cell,
62        crate::routers::responses::create_response,
63    ),
64    components(schemas(
65        // E-02 — typed-entry remember DTOs
66        crate::dto::remember_entry::RememberEntryRequestDTO,
67        crate::dto::remember::RememberResultDTO,
68        crate::dto::remember::RememberItemDTO,
69        crate::dto::remember::WireRememberStatus,
70        // E-09 — sessions DTOs (snake_case wire — Python parity carve-out)
71        crate::dto::sessions::SessionListResponseDTO,
72        crate::dto::sessions::SessionRowDTO,
73        crate::dto::sessions::OrderBy,
74        crate::dto::sessions::RangeWindow,
75        // E-10 — sessions stats DTO (StatsQuery is `IntoParams`-only)
76        crate::dto::sessions::SessionStatsDTO,
77        // E-11 — sessions cost-by-model DTO (CostByModelQuery is `IntoParams`-only)
78        crate::dto::sessions::CostByModelDTO,
79        // E-12 — sessions detail DTO (snake_case wire — Python parity carve-out)
80        crate::dto::sessions::SessionDetailDTO,
81        // P5 settings DTOs
82        crate::dto::settings::SettingsDTO,
83        crate::dto::settings::SettingsPayloadDTO,
84        crate::dto::settings::LLMConfigOutputDTO,
85        crate::dto::settings::LLMConfigInputDTO,
86        crate::dto::settings::VectorDBConfigOutputDTO,
87        crate::dto::settings::VectorDBConfigInputDTO,
88        crate::dto::settings::ConfigChoice,
89        crate::dto::settings::LlmProvider,
90        crate::dto::settings::VectorDbProvider,
91        // P7 notebook + responses DTOs
92        crate::dto::notebooks::NotebookDTO,
93        crate::dto::notebooks::NotebookCellDTO,
94        crate::dto::notebooks::NotebookDataDTO,
95        crate::dto::notebooks::RunCodeDataDTO,
96        crate::dto::notebooks::RunCodeOutcomeDTO,
97        crate::dto::responses::ResponseRequestDTO,
98        crate::dto::responses::CogneeModelDTO,
99        crate::dto::responses::ToolFunctionDTO,
100        crate::dto::responses::FunctionDTO,
101        crate::dto::responses::FunctionParametersDTO,
102        crate::dto::responses::ResponseBodyDTO,
103        crate::dto::responses::ResponseToolCallDTO,
104        crate::dto::responses::FunctionCallDTO,
105        crate::dto::responses::ToolCallOutputDTO,
106        crate::dto::responses::ChatUsageDTO,
107    ))
108)]
109pub struct ApiDoc;
110
111/// `Modify` impl that injects `BearerAuth` and `ApiKeyAuth` security schemes.
112struct SecurityAddon;
113
114impl Modify for SecurityAddon {
115    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
116        let components = openapi.components.get_or_insert_with(Components::default);
117        components.add_security_scheme(
118            "BearerAuth",
119            SecurityScheme::Http(
120                HttpBuilder::new()
121                    .scheme(HttpAuthScheme::Bearer)
122                    .bearer_format("JWT")
123                    .build(),
124            ),
125        );
126        components.add_security_scheme(
127            "ApiKeyAuth",
128            SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::new("X-Api-Key"))),
129        );
130    }
131}
132
133/// Handler for `GET /openapi.json`.  Returns the full OpenAPI document as JSON.
134pub async fn openapi_json() -> impl IntoResponse {
135    Json(ApiDoc::openapi())
136}
cognee_http_server/openapi.rs

cognee_http_server/
openapi.rs
