aide/openapi/
operation.rs

1use crate::{openapi::*, util::*};
2use indexmap::IndexMap;
3use serde::{Deserialize, Serialize};
4
5/// Describes a single API operation on a path.
6#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
7#[serde(rename_all = "camelCase")]
8#[derive(schemars::JsonSchema)]
9pub struct Operation {
10    /// A list of tags for API documentation control.
11    /// Tags can be used for logical grouping of operations
12    /// by resources or any other qualifier.
13    #[serde(default)]
14    #[serde(skip_serializing_if = "Vec::is_empty")]
15    pub tags: Vec<String>,
16    /// A short summary of what the operation does.
17    #[serde(skip_serializing_if = "Option::is_none")]
18    pub summary: Option<String>,
19    /// A verbose explanation of the operation behavior.
20    /// CommonMark syntax MAY be used for rich text representation.
21    #[serde(skip_serializing_if = "Option::is_none")]
22    pub description: Option<String>,
23    /// Additional external documentation for this operation.
24    #[serde(skip_serializing_if = "Option::is_none")]
25    pub external_docs: Option<ExternalDocumentation>,
26    /// Unique string used to identify the operation.
27    /// The id MUST be unique among all operations described in the API.
28    /// Tools and libraries MAY use the operationId to uniquely identify
29    /// an operation, therefore, it is RECOMMENDED to follow common
30    /// programming naming conventions.
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub operation_id: Option<String>,
33    /// A list of parameters that are applicable for this operation.
34    /// If a parameter is already defined at the Path Item, the new
35    /// definition will override it but can never remove it.
36    /// The list MUST NOT include duplicated parameters. A unique
37    /// parameter is defined by a combination of a name and location.
38    /// The list can use the Reference Object to link to parameters
39    /// that are defined at the OpenAPI Object's components/parameters.
40    #[serde(default)]
41    #[serde(skip_serializing_if = "Vec::is_empty")]
42    pub parameters: Vec<ReferenceOr<Parameter>>,
43    /// The request body applicable for this operation.
44    /// The requestBody is fully supported in HTTP methods
45    /// where the HTTP 1.1 specification RFC7231 has explicitly
46    /// defined semantics for request bodies. In other cases where
47    /// the HTTP spec is vague (such as
48    /// [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1),
49    /// [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and
50    /// [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)),
51    /// requestBody is permitted but does not have well-defined semantics and
52    /// SHOULD be avoided if possible.
53    #[serde(skip_serializing_if = "Option::is_none")]
54    pub request_body: Option<ReferenceOr<RequestBody>>,
55    /// The list of possible responses as they are returned
56    /// from executing this operation.
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub responses: Option<Responses>,
59    /// Declares this operation to be deprecated.Default value is false.
60    #[serde(default, skip_serializing_if = "is_false")]
61    pub deprecated: bool,
62    /// A declaration of which security mechanisms can be used for this
63    /// operation. The list of values includes alternative security
64    /// requirement objects that can be used. Only one of the security
65    /// requirement objects need to be satisfied to authorize a request.
66    /// This definition overrides any declared top-level security. To remove
67    /// a top-level security declaration, an empty array can be used.
68    #[serde(default)]
69    #[serde(skip_serializing_if = "Vec::is_empty")]
70    pub security: Vec<SecurityRequirement>,
71    /// An alternative server array to service this operation.
72    /// If an alternative server object is specified at the
73    /// Path Item Object or Root level, it will be overridden by this value.
74    #[serde(default)]
75    #[serde(skip_serializing_if = "Vec::is_empty")]
76    pub servers: Vec<Server>,
77    /// Callbacks for the operation.
78    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
79    pub callbacks: IndexMap<String, ReferenceOr<Callback>>,
80    /// Inline extensions to this object.
81    #[serde(flatten, deserialize_with = "crate::util::deserialize_extensions")]
82    pub extensions: IndexMap<String, serde_json::Value>,
83}
aide/openapi/operation.rs

aide/openapi/
operation.rs
