Skip to content

Commit e7625af

Browse files
committed
docs: document operation methods
1 parent 3f27d96 commit e7625af

File tree

7 files changed

+65
-48
lines changed

7 files changed

+65
-48
lines changed

crates/oas3/src/spec/example.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ pub struct Example {
1616
pub summary: Option<String>,
1717

1818
/// Long description for the example.
19-
/// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
19+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text representation.
2020
#[serde(skip_serializing_if = "Option::is_none")]
2121
pub description: Option<String>,
2222

crates/oas3/src/spec/external_doc.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ pub struct ExternalDoc {
1414
pub url: Url,
1515

1616
/// A short description of the target documentation.
17-
/// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
17+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text representation.
1818
#[serde(skip_serializing_if = "Option::is_none")]
1919
pub description: Option<String>,
2020

crates/oas3/src/spec/link.rs

+3-2
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,9 @@ pub enum Link {
5353
// #[serde(rename = "requestBody")]
5454
// request_body: Any | {expression}
5555
//
56-
/// A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be
57-
/// used for rich text representation.
56+
/// A description of the link.
57+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
58+
/// representation.
5859
#[serde(skip_serializing_if = "Option::is_none")]
5960
description: Option<String>,
6061

crates/oas3/src/spec/operation.rs

+54-41
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ use crate::spec::spec_extensions;
1111
/// Describes a single API operation on a path.
1212
///
1313
/// 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)]
1615
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.
1919
#[serde(default, skip_serializing_if = "Vec::is_empty")]
2020
pub tags: Vec<String>,
2121

@@ -24,43 +24,51 @@ pub struct Operation {
2424
pub summary: Option<String>,
2525

2626
/// 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.
2829
#[serde(skip_serializing_if = "Option::is_none")]
2930
pub description: Option<String>,
3031

3132
/// 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")]
3334
pub external_docs: Option<ExternalDoc>,
3435

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")]
3942
pub operation_id: Option<String>,
4043

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
5357
#[serde(default, skip_serializing_if = "Vec::is_empty")]
5458
pub parameters: Vec<ObjectOrReference<Parameter>>,
5559

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.
5765
#[serde(rename = "requestBody", skip_serializing_if = "Option::is_none")]
5866
pub request_body: Option<ObjectOrReference<RequestBody>>,
5967

6068
/// The list of possible responses as they are returned from executing this operation.
6169
///
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.
6472
///
6573
/// The documentation is not necessarily expected to cover all possible HTTP response codes
6674
/// because they may not be known in advance. However, documentation is expected to cover
@@ -75,19 +83,20 @@ pub struct Operation {
7583
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#responses-object>.
7684
pub responses: Option<BTreeMap<String, ObjectOrReference<Response>>>,
7785

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")]
8795
pub callbacks: BTreeMap<String, Callback>,
8896

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`.
91100
#[serde(skip_serializing_if = "Option::is_none")]
92101
pub deprecated: Option<bool>,
93102

@@ -100,11 +109,11 @@ pub struct Operation {
100109
// /// To remove a top-level security declaration, an empty array can be used.
101110
// pub security: Option<SecurityRequirement>,
102111
//
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")]
108117
pub servers: Vec<Server>,
109118

110119
/// Specification extensions.
@@ -117,6 +126,7 @@ pub struct Operation {
117126
}
118127

119128
impl Operation {
129+
/// Resolves and returns this operation's request body.
120130
pub fn request_body(&self, spec: &Spec) -> Result<RequestBody, Error> {
121131
self.request_body
122132
.as_ref()
@@ -125,6 +135,7 @@ impl Operation {
125135
.map_err(Error::Ref)
126136
}
127137

138+
/// Resolves and returns map of this operation's responses, keyed by status code.
128139
pub fn responses(&self, spec: &Spec) -> BTreeMap<String, Response> {
129140
self.responses
130141
.iter()
@@ -139,6 +150,7 @@ impl Operation {
139150
.collect()
140151
}
141152

153+
/// Resolves and returns list of this operation's parameters.
142154
pub fn parameters(&self, spec: &Spec) -> Result<Vec<Parameter>, Error> {
143155
let params = self
144156
.parameters
@@ -150,6 +162,7 @@ impl Operation {
150162
Ok(params)
151163
}
152164

165+
/// Finds, resolves, and returns one of this operation's parameters by name.
153166
pub fn parameter(&self, search: &str, spec: &Spec) -> Result<Option<Parameter>, Error> {
154167
let param = self
155168
.parameters(spec)?

crates/oas3/src/spec/path_item.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ pub struct PathItem {
2929
pub summary: Option<String>,
3030

3131
/// An optional, string description, intended to apply to all operations in this path.
32-
/// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
32+
///
33+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text representation.
3334
#[serde(skip_serializing_if = "Option::is_none")]
3435
pub description: Option<String>,
3536

crates/oas3/src/spec/request_body.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ use super::{FromRef, MediaType, Ref, RefError, RefType, Spec};
1010
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
1111
pub struct RequestBody {
1212
/// A brief description of the request body. This could contain examples of use.
13-
/// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
13+
///
14+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text representation.
1415
#[serde(skip_serializing_if = "Option::is_none")]
1516
pub description: Option<String>,
1617

crates/oas3/src/spec/response.rs

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ use super::{
1414
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
1515
pub struct Response {
1616
/// A short description of the response.
17-
/// [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
17+
///
18+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text representation.
1819
pub description: Option<String>,
1920

2021
/// Maps a header name to its definition.

0 commit comments

Comments
 (0)