Skip to content

Commit 04fba3b

Browse files
committed
docs: document example methods
1 parent ef3580f commit 04fba3b

File tree

4 files changed

+25
-16
lines changed

4 files changed

+25
-16
lines changed

crates/oas3/examples/printer.rs

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
//! Demonstrates reading an OpenAPI spec file and printing back to stdout.
2+
13
use std::env;
24

35
fn main() -> eyre::Result<()> {

crates/oas3/src/spec/example.rs

+1
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ pub struct Example {
4444
}
4545

4646
impl Example {
47+
/// Returns JSON-encoded bytes of this example's value.
4748
pub fn as_bytes(&self) -> Vec<u8> {
4849
match self.value {
4950
Some(ref val) => serde_json::to_string(val).unwrap().as_bytes().to_owned(),

crates/oas3/src/spec/mod.rs

+4-1
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ impl Spec {
162162
}
163163
}
164164

165-
/// Returns operation matching `operation_id`, if found.
165+
/// Returns a reference to the operation with given `operation_id`, or `None` if not found.
166166
pub fn operation_by_id(&self, operation_id: &str) -> Option<&Operation> {
167167
self.operations()
168168
.find(|(_, _, op)| {
@@ -173,6 +173,7 @@ impl Spec {
173173
.map(|(_, _, op)| op)
174174
}
175175

176+
/// Returns a reference to the operation with given `method` and `path`, or `None` if not found.
176177
pub fn operation(&self, method: &http::Method, path: &str) -> Option<&Operation> {
177178
let resource = self.paths.as_ref()?.get(path)?;
178179

@@ -189,6 +190,7 @@ impl Spec {
189190
}
190191
}
191192

193+
/// Returns an iterator over all the operations defined in this spec.
192194
pub fn operations(&self) -> impl Iterator<Item = (String, Method, &Operation)> {
193195
let paths = &self.paths;
194196

@@ -218,6 +220,7 @@ impl Spec {
218220
ops.into_iter()
219221
}
220222

223+
/// Returns a reference to the primary (first) server definition.
221224
pub fn primary_server(&self) -> Option<&Server> {
222225
self.servers.first()
223226
}

crates/oas3/src/spec/server.rs

+18-15
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,42 @@ use serde::{Deserialize, Serialize};
55
/// An object representing a Server.
66
///
77
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#server-object>.
8-
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
8+
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
99
pub struct Server {
10-
/// A URL to the target host. This URL supports Server Variables and MAY be relative, to
11-
/// indicate that the host location is relative to the location where the OpenAPI document
12-
/// is being served. Variable substitutions will be made when a variable is named
13-
/// in {brackets}.
10+
/// A URL to the target host.
11+
///
12+
/// This URL supports Server Variables and MAY be relative, to indicate that the host location
13+
/// is relative to the location where the OpenAPI document is being served. Variable
14+
/// substitutions will be made when a variable is named in {brackets}.
1415
pub url: String,
1516

16-
/// An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
17+
/// An optional string describing the host designated by the URL.
18+
///
19+
/// CommonMark syntax MAY be used for rich text representation.
1720
#[serde(skip_serializing_if = "Option::is_none")]
1821
pub description: Option<String>,
1922

20-
/// A map between a variable name and its value. The value is used for substitution in
21-
/// the server's URL template.
22-
#[serde(default)]
23-
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
23+
/// A map between a variable name and its value.
24+
///
25+
/// The value is used for substitution in the server's URL template.
26+
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
2427
pub variables: BTreeMap<String, ServerVariable>,
2528
}
2629

2730
/// An object representing a Server Variable for server URL template substitution.
2831
///
2932
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#server-variable-object>.
30-
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
33+
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
3134
pub struct ServerVariable {
3235
/// The default value to use for substitution, and to send, if an alternate value is not
33-
/// supplied. Unlike the Schema Object's default, this value MUST be provided by the consumer.
36+
/// supplied.
37+
///
38+
/// Unlike the Schema Object's default, this value MUST be provided by the consumer.
3439
pub default: String,
3540

3641
/// An enumeration of string values to be used if the substitution options are from a limited
3742
/// set.
38-
#[serde(default)]
39-
#[serde(rename = "enum")]
40-
#[serde(skip_serializing_if = "Vec::is_empty")]
43+
#[serde(rename = "enum", default, skip_serializing_if = "Vec::is_empty")]
4144
pub substitutions_enum: Vec<String>,
4245

4346
/// An optional description for the server variable. [CommonMark] syntax MAY be used for rich

0 commit comments

Comments
 (0)