docs: document example methods

Author: robjtede

crates/oas3/examples/printer.rs

@@ -1,3 +1,5 @@
+//! Demonstrates reading an OpenAPI spec file and printing back to stdout.
+
 use std::env;
 
 fn main() -> eyre::Result<()> {

crates/oas3/src/spec/example.rs

@@ -44,6 +44,7 @@ pub struct Example {
 }
 
 impl Example {
+    /// Returns JSON-encoded bytes of this example's value.
     pub fn as_bytes(&self) -> Vec<u8> {
         match self.value {
             Some(ref val) => serde_json::to_string(val).unwrap().as_bytes().to_owned(),

crates/oas3/src/spec/mod.rs

@@ -162,7 +162,7 @@ impl Spec {
         }
     }
 
-    /// Returns operation matching `operation_id`, if found.
+    /// Returns a reference to the operation with given `operation_id`, or `None` if not found.
     pub fn operation_by_id(&self, operation_id: &str) -> Option<&Operation> {
         self.operations()
             .find(|(_, _, op)| {
@@ -173,6 +173,7 @@ impl Spec {
             .map(|(_, _, op)| op)
     }
 
+    /// Returns a reference to the operation with given `method` and `path`, or `None` if not found.
     pub fn operation(&self, method: &http::Method, path: &str) -> Option<&Operation> {
         let resource = self.paths.as_ref()?.get(path)?;
 
@@ -189,6 +190,7 @@ impl Spec {
         }
     }
 
+    /// Returns an iterator over all the operations defined in this spec.
     pub fn operations(&self) -> impl Iterator<Item = (String, Method, &Operation)> {
         let paths = &self.paths;
 
@@ -218,6 +220,7 @@ impl Spec {
         ops.into_iter()
     }
 
+    /// Returns a reference to the primary (first) server definition.
     pub fn primary_server(&self) -> Option<&Server> {
         self.servers.first()
     }

crates/oas3/src/spec/server.rs

@@ -5,39 +5,42 @@ use serde::{Deserialize, Serialize};
 /// An object representing a Server.
 ///
 /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#server-object>.
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
 pub struct Server {
-    /// A URL to the target host. This URL supports Server Variables and MAY be relative, to
-    /// indicate that the host location is relative to the location where the OpenAPI document
-    /// is being served. Variable substitutions will be made when a variable is named
-    /// in {brackets}.
+    /// A URL to the target host.
+    ///
+    /// This URL supports Server Variables and MAY be relative, to indicate that the host location
+    /// is relative to the location where the OpenAPI document is being served. Variable
+    /// substitutions will be made when a variable is named in {brackets}.
     pub url: String,
 
-    /// An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+    /// An optional string describing the host designated by the URL.
+    ///
+    /// CommonMark syntax MAY be used for rich text representation.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
 
-    /// A map between a variable name and its value. The value is used for substitution in
-    /// the server's URL template.
-    #[serde(default)]
-    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    /// A map between a variable name and its value.
+    ///
+    /// The value is used for substitution in the server's URL template.
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub variables: BTreeMap<String, ServerVariable>,
 }
 
 /// An object representing a Server Variable for server URL template substitution.
 ///
 /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#server-variable-object>.
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
 pub struct ServerVariable {
     /// The default value to use for substitution, and to send, if an alternate value is not
-    /// supplied. Unlike the Schema Object's default, this value MUST be provided by the consumer.
+    /// supplied.
+    ///
+    /// Unlike the Schema Object's default, this value MUST be provided by the consumer.
     pub default: String,
 
     /// An enumeration of string values to be used if the substitution options are from a limited
     /// set.
-    #[serde(default)]
-    #[serde(rename = "enum")]
-    #[serde(skip_serializing_if = "Vec::is_empty")]
+    #[serde(rename = "enum", default, skip_serializing_if = "Vec::is_empty")]
     pub substitutions_enum: Vec<String>,
 
     /// An optional description for the server variable. [CommonMark] syntax MAY be used for rich