1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use super::OpenApiFromQuery;
use crate::gen::OpenApiGenerator;
use okapi::openapi3::*;
use schemars::schema::{Schema, SchemaObject};
use schemars::JsonSchema;
use std::result::Result as StdResult;

type Result = crate::Result<Vec<Parameter>>;

/// Given an object that implements the `JsonSchema` generate all the `Parameter`
/// that are used to create documentation.
/// Use when manually implementing a
/// [Query Guard](https://docs.rs/rocket/latest/rocket/request/trait.FromQuery.html).
/// Example:
/// ```
/// use rocket::request::{Query, FromQuery};
/// use serde::{Serialize, Deserialize};
/// use schemars::JsonSchema;
/// use rocket_okapi::{
///     gen::OpenApiGenerator,
///     request::OpenApiFromQuery,
///     request::get_nested_query_parameters
/// };
///
/// #[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
/// pub struct ApiPagination{
///     page: Option<u32>,
///     per_page: Option<u32>,
/// }
///
/// impl<'q> FromQuery<'q> for ApiPagination {
///     type Error = String;// Some kind of error
///
///     fn from_query(_query: Query<'q>) -> Result<Self, Self::Error> {
///         Ok(ApiPagination::default())
///     }
/// }
///
/// impl<'r> OpenApiFromQuery<'r> for ApiPagination {
///     fn query_multi_parameter(gen: &mut OpenApiGenerator, name: String, required: bool)
///     -> rocket_okapi::Result<Vec<okapi::openapi3::Parameter>> {
///         Ok(get_nested_query_parameters::<ApiPagination>(gen, name, required))
///     }
/// }
/// ```
pub fn get_nested_query_parameters<T>(
    gen: &mut OpenApiGenerator,
    _name: String,
    required: bool,
) -> Vec<Parameter>
where
    T: JsonSchema,
{
    let schema = gen.json_schema_no_ref::<T>();
    // Get a list of properties from the structure.
    let mut properties: schemars::Map<String, Schema> = schemars::Map::new();
    if let Some(object) = schema.object {
        properties = object.properties;
    }
    // Create all the `Parameter` for every property
    let mut parameter_list: Vec<Parameter> = Vec::new();
    for (key, property) in properties {
        let prop_schema = match property {
            Schema::Object(x) => x,
            _ => SchemaObject::default(),
        };
        let mut parameter_required = required;
        // Check if parameter is optional (only is not already optional)
        if parameter_required {
            for (key, value) in &prop_schema.extensions {
                if key == "nullable" {
                    if let Some(nullable) = value.as_bool() {
                        parameter_required = !nullable;
                    }
                }
            }
        }
        let description = prop_schema
            .metadata
            .as_ref()
            .and_then(|m| m.description.clone());
        parameter_list.push(Parameter {
            name: key,
            location: "query".to_owned(),
            description,
            required: parameter_required,
            deprecated: false,
            allow_empty_value: false,
            value: ParameterValue::Schema {
                style: None,
                explode: None,
                allow_reserved: false,
                schema: prop_schema,
                example: None,
                examples: None,
            },
            extensions: Default::default(),
        });
    }
    parameter_list
}

impl<'r, T: OpenApiFromQuery<'r>> OpenApiFromQuery<'r> for StdResult<T, T::Error> {
    fn query_multi_parameter(gen: &mut OpenApiGenerator, name: String, _required: bool) -> Result {
        T::query_multi_parameter(gen, name, false)
    }
}

impl<'r, T: OpenApiFromQuery<'r>> OpenApiFromQuery<'r> for Option<T> {
    fn query_multi_parameter(gen: &mut OpenApiGenerator, name: String, _required: bool) -> Result {
        T::query_multi_parameter(gen, name, false)
    }
}

// All fields are required.
// Does not allow extra fields.
impl<'r, T> OpenApiFromQuery<'r> for rocket::request::Form<T>
where
    T: rocket::request::FromForm<'r> + JsonSchema,
{
    fn query_multi_parameter(gen: &mut OpenApiGenerator, name: String, required: bool) -> Result {
        Ok(get_nested_query_parameters::<T>(gen, name, required))
    }
}

// All fields are required.
// Does allow extra fields. (automatically discards extra fields without error)
impl<'r, T> OpenApiFromQuery<'r> for rocket::request::LenientForm<T>
where
    T: rocket::request::FromForm<'r> + JsonSchema,
{
    fn query_multi_parameter(gen: &mut OpenApiGenerator, name: String, required: bool) -> Result {
        Ok(get_nested_query_parameters::<T>(gen, name, required))
    }
}