@@ -11,11 +11,11 @@ use crate::spec::spec_extensions;
11
11
/// Describes a single API operation on a path.
12
12
///
13
13
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object>.
14
- #[ derive( Clone , Debug , Deserialize , Serialize , PartialEq , Default ) ]
15
- // #[serde(rename_all = "lowercase")]
14
+ #[ derive( Debug , Clone , Default , PartialEq , Deserialize , Serialize ) ]
16
15
pub struct Operation {
17
- /// A list of tags for API documentation control. Tags can be used for logical grouping of
18
- /// operations by resources or any other qualifier.
16
+ /// A list of tags for API documentation control.
17
+ ///
18
+ /// Tags can be used for logical grouping of operations by resources or any other qualifier.
19
19
#[ serde( default , skip_serializing_if = "Vec::is_empty" ) ]
20
20
pub tags : Vec < String > ,
21
21
@@ -24,43 +24,51 @@ pub struct Operation {
24
24
pub summary : Option < String > ,
25
25
26
26
/// A verbose explanation of the operation behavior.
27
- /// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
27
+ ///
28
+ /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text representation.
28
29
#[ serde( skip_serializing_if = "Option::is_none" ) ]
29
30
pub description : Option < String > ,
30
31
31
32
/// Additional external documentation for this operation.
32
- #[ serde( skip_serializing_if = "Option::is_none " , rename = "externalDocs " ) ]
33
+ #[ serde( rename = "externalDocs " , skip_serializing_if = "Option::is_none " ) ]
33
34
pub external_docs : Option < ExternalDoc > ,
34
35
35
- /// Unique string used to identify the operation. The id MUST be unique among all operations
36
- /// described in the API. Tools and libraries MAY use the operationId to uniquely identify an
37
- /// operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
38
- #[ serde( skip_serializing_if = "Option::is_none" , rename = "operationId" ) ]
36
+ /// String used to uniquely identify the operation within this spec.
37
+ ///
38
+ /// The ID MUST be unique among all operations described in the API. Tools and libraries MAY use
39
+ /// the operation ID to uniquely identify an operation, therefore, it is RECOMMENDED to follow
40
+ /// common programming naming conventions.
41
+ #[ serde( rename = "operationId" , skip_serializing_if = "Option::is_none" ) ]
39
42
pub operation_id : Option < String > ,
40
43
41
- /// A list of parameters that are applicable for this operation. If a parameter is already
42
- /// defined at the
43
- /// [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#pathItemParameters),
44
- /// the new definition will override it but can never remove it. The list MUST NOT
45
- /// include duplicated parameters. A unique parameter is defined by a combination of a
46
- /// [name](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterName)
47
- /// and
48
- /// [location](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn).
49
- /// The list can use the
50
- /// [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#reference-object)
51
- /// to link to parameters that are defined at the
52
- /// [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#components-parameters).
44
+ /// A list of parameters that are applicable for this operation.
45
+ ///
46
+ /// If a parameter is already defined at the [Path Item], the new definition will override it
47
+ /// but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter
48
+ /// is defined by a combination of a [name] and [location] The list can use the
49
+ /// [Reference Object] to link to parameters that are defined at the
50
+ /// [OpenAPI Object's components/parameters].
51
+ ///
52
+ /// [Path Item]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#pathItemParameters
53
+ /// [name]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterName
54
+ /// [location]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn
55
+ /// [Reference Object]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#reference-object
56
+ /// [OpenAPI Object's components/parameters]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#components-parameters
53
57
#[ serde( default , skip_serializing_if = "Vec::is_empty" ) ]
54
58
pub parameters : Vec < ObjectOrReference < Parameter > > ,
55
59
56
- /// The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
60
+ /// The request body applicable for this operation.
61
+ ///
62
+ /// The `requestBody` is only supported in HTTP methods where the HTTP/1.1 specification RFC
63
+ /// 7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec
64
+ /// is vague, `requestBody` SHALL be ignored by consumers.
57
65
#[ serde( rename = "requestBody" , skip_serializing_if = "Option::is_none" ) ]
58
66
pub request_body : Option < ObjectOrReference < RequestBody > > ,
59
67
60
68
/// The list of possible responses as they are returned from executing this operation.
61
69
///
62
- /// A container for the expected responses of an operation. The container maps a HTTP
63
- /// response code to the expected response.
70
+ /// A container for the expected responses of an operation. The container maps a HTTP response
71
+ /// code to the expected response.
64
72
///
65
73
/// The documentation is not necessarily expected to cover all possible HTTP response codes
66
74
/// because they may not be known in advance. However, documentation is expected to cover
@@ -75,19 +83,20 @@ pub struct Operation {
75
83
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#responses-object>.
76
84
pub responses : Option < BTreeMap < String , ObjectOrReference < Response > > > ,
77
85
78
- /// A map of possible out-of band callbacks related to the parent operation. The key is
79
- /// a unique identifier for the Callback Object. Each value in the map is a
80
- /// [ Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#callback-object)
81
- /// that describes a request that may be initiated by the API provider and the
82
- /// expected responses. The key value used to identify the callback object is
83
- /// an expression, evaluated at runtime, that identifies a URL to use for the
84
- /// callback operation.
85
- # [ serde ( default ) ]
86
- #[ serde( skip_serializing_if = "BTreeMap::is_empty" ) ]
86
+ /// A map of possible out-of band callbacks related to the parent operation.
87
+ ///
88
+ /// The key is a unique identifier for the Callback Object. Each value in the map is a
89
+ /// [Callback Object] that describes a request that may be initiated by the API provider and the
90
+ /// expected responses. The key value used to identify the callback object is an expression,
91
+ /// evaluated at runtime, that identifies a URL to use for the callback operation.
92
+ ///
93
+ /// [Callback Object]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#callback-object
94
+ #[ serde( default , skip_serializing_if = "BTreeMap::is_empty" ) ]
87
95
pub callbacks : BTreeMap < String , Callback > ,
88
96
89
- /// Declares this operation to be deprecated. Consumers SHOULD refrain from usage
90
- /// of the declared operation. Default value is `false`.
97
+ /// Declares this operation to be deprecated.
98
+ ///
99
+ /// Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
91
100
#[ serde( skip_serializing_if = "Option::is_none" ) ]
92
101
pub deprecated : Option < bool > ,
93
102
@@ -100,11 +109,11 @@ pub struct Operation {
100
109
// /// To remove a top-level security declaration, an empty array can be used.
101
110
// pub security: Option<SecurityRequirement>,
102
111
//
103
- /// An alternative `server` array to service this operation. If an alternative `server`
104
- /// object is specified at the Path Item Object or Root level, it will be overridden by
105
- /// this value.
106
- # [ serde ( default ) ]
107
- #[ serde( skip_serializing_if = "Vec::is_empty" ) ]
112
+ /// An alternative `server` array to service this operation.
113
+ ///
114
+ /// If an alternative `server` object is specified at the Path Item Object or Root level, it
115
+ /// will be overridden by this value.
116
+ #[ serde( default , skip_serializing_if = "Vec::is_empty" ) ]
108
117
pub servers : Vec < Server > ,
109
118
110
119
/// Specification extensions.
@@ -117,6 +126,7 @@ pub struct Operation {
117
126
}
118
127
119
128
impl Operation {
129
+ /// Resolves and returns this operation's request body.
120
130
pub fn request_body ( & self , spec : & Spec ) -> Result < RequestBody , Error > {
121
131
self . request_body
122
132
. as_ref ( )
@@ -125,6 +135,7 @@ impl Operation {
125
135
. map_err ( Error :: Ref )
126
136
}
127
137
138
+ /// Resolves and returns map of this operation's responses, keyed by status code.
128
139
pub fn responses ( & self , spec : & Spec ) -> BTreeMap < String , Response > {
129
140
self . responses
130
141
. iter ( )
@@ -139,6 +150,7 @@ impl Operation {
139
150
. collect ( )
140
151
}
141
152
153
+ /// Resolves and returns list of this operation's parameters.
142
154
pub fn parameters ( & self , spec : & Spec ) -> Result < Vec < Parameter > , Error > {
143
155
let params = self
144
156
. parameters
@@ -150,6 +162,7 @@ impl Operation {
150
162
Ok ( params)
151
163
}
152
164
165
+ /// Finds, resolves, and returns one of this operation's parameters by name.
153
166
pub fn parameter ( & self , search : & str , spec : & Spec ) -> Result < Option < Parameter > , Error > {
154
167
let param = self
155
168
. parameters ( spec) ?
0 commit comments