Crate churust_openapi 

OpenAPI 3.1 descriptions for Churust applications.

The router already knows every path and method that exists. This crate turns that inventory into an OpenAPI document, and gives you somewhere to hang the parts a router cannot know: what an operation is for, what it accepts, and what it answers with.

use churust_core::{Call, Churust, TestClient};
use churust_openapi::{OpenApi, Operation};
use http::Method;

// 1. Register the application's own routes.
let builder = Churust::server().routing(|r| {
    r.get("/users/{id}", |_c: Call| async { "a user" });
    r.post("/users", |_c: Call| async { "created" });
});

// 2. Describe them. Paths and parameters come from the router; the prose
//    and the responses come from you.
let api = OpenApi::new("Users API", "1.0.0")
    .from_routes(builder.routes())
    .operation(
        Method::GET,
        "/users/{id}",
        Operation::new()
            .summary("Fetch one user")
            .response(200, "The user")
            .response(404, "No such user"),
    );

// 3. Serve it.
let app = builder.routing(|r| api.mount(r, "/openapi.json")).build();

let res = TestClient::new(app).get("/openapi.json").send().await;
assert_eq!(res.header("content-type"), Some("application/json"));
assert!(res.text().contains("Fetch one user"));

What is generated and what is not

Generated from the router: every path, every method on it, and a path parameter for each {name} in the pattern. Those cannot drift from the application, because they are the application.

Not generated: request and response schemas. Churust handlers are ordinary Rust functions and their extractor types are erased by the time a router exists, so anything claiming to infer a schema here would be inferring it from an annotation you wrote anyway. Describing an operation is explicit, and the schema helpers take a serde_json::Value so a schema derived by any other crate drops straight in.

Drift

A description of a route that no longer exists is worse than no description at all. undescribed and stale report both directions of drift, so a test can fail the build when they disagree rather than a client finding out.

Structs

OpenApi

An OpenAPI 3.1 document under construction.

Operation

One documented operation: a method on a path.