rocket_okapi 0.7.0-alpha-1

OpenAPI (AKA Swagger) document generation for Rocket applications
Documentation 
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

use super::{get_nested_form_parameters, OpenApiFromForm, OpenApiFromFormField};
use crate::gen::OpenApiGenerator;
use okapi::openapi3::{Parameter, ParameterValue};
use rocket::form::Result as FormResult;
use schemars::JsonSchema;

type Result = crate::Result<Parameter>;

macro_rules! impl_from_form_param {
    ($ty: path) => {
        impl<'r> OpenApiFromFormField<'r> for $ty {
            fn form_parameter(gen: &mut OpenApiGenerator, name: String, required: bool) -> Result {
                let schema = gen.json_schema::<$ty>();
                Ok(Parameter {
                    name,
                    // Currently it's used also by query parameters which are more common than forms
                    location: "query".to_owned(),
                    description: None,
                    required,
                    deprecated: false,
                    allow_empty_value: false,
                    value: ParameterValue::Schema {
                        style: None,
                        explode: None,
                        allow_reserved: false,
                        schema,
                        example: None,
                        examples: None,
                    },
                    extensions: okapi::Map::default(),
                })
            }
        }
    };
}

impl_from_form_param!(f32);
impl_from_form_param!(f64);
impl_from_form_param!(isize);
impl_from_form_param!(i8);
impl_from_form_param!(i16);
impl_from_form_param!(i32);
impl_from_form_param!(i64);
impl_from_form_param!(i128);
impl_from_form_param!(usize);
impl_from_form_param!(u8);
impl_from_form_param!(u16);
impl_from_form_param!(u32);
impl_from_form_param!(u64);
impl_from_form_param!(u128);
impl_from_form_param!(bool);
impl_from_form_param!(String);

impl<'r> OpenApiFromFormField<'r> for &'r str {
    fn form_parameter(gen: &mut OpenApiGenerator, name: String, required: bool) -> Result {
        let schema = gen.json_schema::<str>();
        Ok(Parameter {
            name,
            location: "query".to_owned(),
            description: None,
            required,
            deprecated: false,
            allow_empty_value: false,
            value: ParameterValue::Schema {
                style: None,
                explode: None,
                allow_reserved: false,
                schema,
                example: None,
                examples: None,
            },
            extensions: okapi::Map::default(),
        })
    }
}

// OpenAPI specification does not support optional path params, so we leave `required` as true,
// even for Options and Results.
impl<'r, T: OpenApiFromFormField<'r>> OpenApiFromFormField<'r> for FormResult<'r, T> {
    fn form_parameter(gen: &mut OpenApiGenerator, name: String, required: bool) -> Result {
        T::form_parameter(gen, name, required)
    }
}

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

impl<'r, T> OpenApiFromForm<'r> for T
where
    T: rocket::form::FromForm<'r> + JsonSchema,
{
    fn form_multi_parameter(
        gen: &mut OpenApiGenerator,
        name: String,
        required: bool,
    ) -> crate::Result<Vec<Parameter>> {
        Ok(get_nested_form_parameters::<T>(gen, name, required))
    }
}