Struct RouteHandle 

pub struct RouteHandle<'r> { /* private fields */ }

Returned by get/post/… so a route can be named after registration.

Implementations

impl RouteHandle<'_>

pub fn name(self, name: &str) -> Self

Name the route for url_for and route:list.

pub fn describe(self, summary: &str) -> Self

Say what this route does, in one line.

Documentation is attached here rather than kept in a separate file, so it cannot drift away from the route it describes.

pub fn tag(self, tag: &str) -> Self

Group this route under a heading in generated documentation.

pub fn responds(self, status: u16, description: &str) -> Self

Document a response this route can return.

pub fn param(self, name: &str, description: &str) -> Self

Describe a parameter. Undescribed path parameters are still documented, just without prose.

pub fn middleware(self, middleware: impl Middleware) -> Self

Add middleware to this one route.

A group is the right place for middleware several routes share. This is for the case a group cannot express: routes on one prefix that need different guards, which is what a resource with a permission per verb looks like — users.view on the index, users.delete on the delete. Without this, each verb needs a group of its own and the prefix stops reading as one resource.

It runs after the group’s middleware and before the handler.

pub fn deprecated(self) -> Self

Mark the route as deprecated in generated documentation.

pub fn deprecated_at(self, date: &str) -> Self

Say when the route was deprecated, as YYYY-MM-DD.

Responses then carry Deprecation: @<unix time> (RFC 9745), which is how a client library learns to warn its own developers. Implies RouteHandle::deprecated.

Panics

On a date that is not YYYY-MM-DD — this is called at startup, with a literal, and a typo should fail there rather than send garbage.

pub fn sunset(self, date: &str) -> Self

Say when the route will stop working, as YYYY-MM-DD.

Responses then carry Sunset (RFC 8594) with that date, and the route is marked deprecated. Nothing removes the route on the day — that is a deploy, and a person’s decision — but every client has been told.

Panics

On a date that is not YYYY-MM-DD, for the reason given on RouteHandle::deprecated_at.