rocket_autodocu/request/
mod.rs

1mod from_data_impls;
2mod from_form_multi_param_impls;
3mod from_form_param_impls;
4mod from_param_impls;
5mod from_request_impls;
6mod from_segments_impls;
7
8use super::gen::OpenApiGenerator;
9use super::Result;
10use autodocu::openapi3::{
11    Parameter, RequestBody, Responses, SecurityRequirement, SecurityScheme,
12};
13
14/// Expose this to the public to be use when manually implementing a
15/// [Form Guard](https://api.rocket.rs/master/rocket/form/trait.FromForm.html).
16pub use from_form_multi_param_impls::get_nested_form_parameters;
17
18/// This trait is used to document the request body that implements
19/// [`FromData`](rocket::data::FromData).
20pub trait OpenApiFromData<'r>: rocket::data::FromData<'r> {
21    /// Return a [`RequestBody`] containing the information required to document the
22    /// [`FromData`](rocket::data::FromData) object.
23    fn request_body(gen: &mut OpenApiGenerator) -> Result<RequestBody>;
24}
25
26/// This trait is used to document a dynamic part of a path that implements
27/// [`FromParam`](rocket::request::FromParam).
28/// For example `<user_id>` in route path.
29pub trait OpenApiFromParam<'r>: rocket::request::FromParam<'r> {
30    /// Return a [`Parameter`] containing the information required to document the
31    /// [`FromParam`](rocket::request::FromParam) path parameter.
32    fn path_parameter(gen: &mut OpenApiGenerator, name: String) -> Result<Parameter>;
33}
34
35/// This trait is used to document a dynamic path segment that implements
36/// [`FromSegments`](rocket::request::FromSegments).
37/// For example `<param..>` in route path.
38pub trait OpenApiFromSegments<'r>: rocket::request::FromSegments<'r> {
39    /// Return a [`Parameter`] containing the information required to document the
40    /// [`FromSegments`](rocket::request::FromSegments) path parameter.
41    fn path_multi_parameter(gen: &mut OpenApiGenerator, name: String) -> Result<Parameter>;
42}
43
44/// This trait is used to document a query guard segment that implements
45/// [`FromFormField`](rocket::form::FromFormField).
46/// For example `?<param>` in the route's query part.
47pub trait OpenApiFromFormField<'r>: rocket::form::FromFormField<'r> {
48    /// Return a [`Parameter`] containing the information required to document the
49    /// [`FromFormField`](rocket::form::FromFormField) route's query part.
50    fn form_parameter(
51        gen: &mut OpenApiGenerator,
52        name: String,
53        required: bool,
54    ) -> Result<Parameter>;
55}
56
57/// This trait is used to document multiple query guard segments that implement
58/// [`FromForm`](rocket::form::FromForm).
59/// For example `?<param>` in the route's query part.
60pub trait OpenApiFromForm<'r>: rocket::form::FromForm<'r> {
61    /// Return a [`Vec<Parameter>`] containing the information required to document the
62    /// [`FromForm`](rocket::form::FromForm) route's query part.
63    fn form_multi_parameter(
64        gen: &mut OpenApiGenerator,
65        name: String,
66        required: bool,
67    ) -> Result<Vec<Parameter>>;
68}
69
70/// Used as a return type for [`OpenApiFromRequest`] trait.
71/// Defines what requirements a Request Guard needs in order to be validated.
72#[allow(clippy::large_enum_variant)]
73pub enum RequestHeaderInput {
74    /// This request header requires no input anywhere
75    None,
76    /// Useful for when you want to set a header per route.
77    Parameter(Parameter),
78    /// The request guard implements a security scheme.
79    ///
80    /// Parameters:
81    /// - The name of the [`SecurityScheme`].
82    /// - [`SecurityScheme`] is global definition of the authentication (per OpenApi spec).
83    /// - [`SecurityRequirement`] is the requirements for the route.
84    Security(String, SecurityScheme, SecurityRequirement),
85}
86
87// Re-export derive trait here for convenience.
88pub use rocket_autodocu_codegen::OpenApiFromRequest;
89
90/// Trait that needs to be implemented for all types that implement
91/// [`FromRequest`](rocket::request::FromRequest).
92/// This trait specifies what headers or other parameters are required for this
93/// [Request Guards](https://rocket.rs/v0.5-rc/guide/requests/#request-guards)
94/// to be validated successfully.
95///
96/// If it does not quire any headers or parameters you can use the derive macro:
97/// ```rust,ignore
98/// use rocket_autodocu::request::OpenApiFromRequest;
99///
100/// #[derive(OpenApiFromRequest)]
101/// pub struct MyStructName;
102/// ```
103pub trait OpenApiFromRequest<'a>: rocket::request::FromRequest<'a> {
104    /// Specifies what headers or other parameters are required for this Request Guards to validate
105    /// successfully.
106    fn from_request_input(
107        gen: &mut OpenApiGenerator,
108        name: String,
109        required: bool,
110    ) -> Result<RequestHeaderInput>;
111
112    /// Optionally add responses to the Request Guard.
113    /// This can be used for when the request guard could return a "401 Unauthorized".
114    /// Or any other responses, other then one from the default response.
115    fn get_responses(_gen: &mut OpenApiGenerator) -> Result<Responses> {
116        Ok(Responses::default())
117    }
118}
rocket_autodocu/request/mod.rs

rocket_autodocu/request/
mod.rs
