Crate kynos 

An idiomatic, performance-focused framework for building REST APIs with first-class OpenAPI 3.1 and 3.2 support.

The idea

Kynos only lets you build APIs it can fully describe. Every handler input describes itself as a Parameter or a Request Body; every handler output describes itself as a Responses Object; every interceptor declares what it contributes to the description. Anything that cannot be described does not compile.

The emitted document is therefore not documentation that drifts from the code — it is a checked contract derived from the same types the server runs on.

What this costs you

Several things other Rust frameworks offer are absent, because OpenAPI cannot express them: wildcard routes, opaque middleware, raw request access, runtime-chosen status codes, WebSockets. The unchecked feature provides escape hatches for the first three, at the price of a description that is no longer authoritative. See the README for the full list and the reasoning.

The guarantees, as compile-fail tests

These are the claims above, stated as code that must not compile. They run as part of the doc test suite, so a regression in any of them is a test failure rather than a documentation inaccuracy.

A path template that is not a legal Paths key — no leading slash:

kynos::path!("users/{id}");

A template repeating a variable, which OpenAPI 3.2 forbids outright:

kynos::path!("/tenants/{id}/users/{id}");

A template carrying a query string, which is not part of a path:

kynos::path!("/users?page=1");

And the one that is valid:

let template = kynos::path!("/users/{id}");
assert_eq!(template.variables(), ["id"]);

Further guarantees are stated where they belong: that serde_json::Value is not describable, and that a context providing no Db cannot satisfy Inject<Db>.

Feature flags

openapi31 is the baseline; openapi32 is a strict superset that unlocks Server-Sent Events, streaming bodies and whole-query-string parameters, none of which OpenAPI 3.1 can describe. Enabling it is additive: Cargo unifies features across a dependency graph, so the model types it extends are non_exhaustive and a match over one keeps compiling either way. The default-on json feature adds application JSON request and response codecs; it does not control OpenAPI document serialization or the framework’s problem-details responses.

The default-on server feature provides the server module. It is built on tokio, which is the only supported runtime: Kynos does not abstract over the runtime and offers no flag selecting another one.

Re-exports

pub use crate::error::Error;

pub use crate::error::Result;

pub use crate::error::problem::Problem;

pub use crate::router::Router;

pub use crate::router::endpoint::Endpoint;

pub use kynos_openapi as openapi;

Modules

di

Dependency injection.

error

Errors, and the one recommended way to represent them on the wire.

extract

Turning a request into a handler’s arguments.

handler

The bridge from an async fn to an operation.

http

The HTTP types Kynos builds on.

middleware

Middleware that declares what it does to the contract.

prelude

Everything a typical application needs, in one import.

response

Turning a handler’s return value into a response — and into a Responses Object.

router

Routing, grouping, and the path from code to description.

schema

Describing Rust types as JSON Schema.

security

Authentication and authorization, described by construction.

server

Serving a built router.

test

Driving a router in-process, without a socket.

unchecked

Escape hatches, and what they cost.

Macros

assets

Compiles a directory into the binary as a described asset set.

path

A path template validated at compile time.

routes

Collects operations for mounting.

Attribute Macros

delete

Declares a DELETE operation. See get for the syntax.

get

Declares a GET operation.

head

Declares a HEAD operation. See get for the syntax.

operation

Declares an operation for a method with no dedicated attribute.

options

Declares an OPTIONS operation. See get for the syntax.

patch

Declares a PATCH operation. See get for the syntax.

post

Declares a POST operation. See get for the syntax.

put

Declares a PUT operation. See get for the syntax.

query

Declares a QUERY operation.

trace

Declares a TRACE operation. See get for the syntax.

Derive Macros

ApiError

Maps an error type to RFC 9457 problem details.

CookieParams

Declares a group of request cookies.

HeaderParams

Declares a group of request or response headers.

MultipartForm

Declares the fields of a multipart/form-data body, in both directions.

PathParams

Declares a group of path parameters.

Provider

Declares an application context, emitting one Provides implementation per field.

QueryParams

Declares a group of query parameters.

Reply

Declares a closed set of responses, one variant per status.

Schema

Describes a type as JSON Schema.

SecurityScheme

Declares a security scheme.

Tag

Declares a tag.