docs: document ref fields

Author: robjtede

crates/oas3/CHANGELOG.md

@@ -4,7 +4,8 @@
 
 - Add `spec::Contact::validate_email()` method.
 - Expose the `spec::ClientCredentialsFlow::token_url` field.
-- Rename `Error::{SemVerError => Semver}` variant.
+- Rename `Error::{SemVerError => Semver}` enum variant.
+- Rename `spec::RefError::{InvalidType => UnknownType}` enum variant.
 
 ## 0.12.1
 

crates/oas3/src/spec/link.rs

@@ -6,41 +6,47 @@ use super::{spec_extensions, Server};
 
 /// The Link object represents a possible design-time link for a response.
 ///
-/// The presence of a link does not guarantee the caller's ability to successfully invoke it,
-/// rather it provides a known relationship and traversal mechanism between responses and
-/// other operations.
+/// The presence of a link does not guarantee the caller's ability to successfully invoke it, rather
+/// it provides a known relationship and traversal mechanism between responses and other operations.
 ///
 /// Unlike _dynamic_ links (i.e. links provided *in* the response payload), the OAS linking
 /// mechanism does not require link information in the runtime response.
 ///
-/// For computing links, and providing instructions to execute them, a
-/// [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#runtimeExpression)
-/// is used for accessing values in an operation and using them as parameters while invoking
-/// the linked operation.
+/// For computing links, and providing instructions to execute them, a [runtime expression] is used
+/// for accessing values in an operation and using them as parameters while invoking the linked
+/// operation.
+///
+/// The `operationRef` and `operationId` fields are mutually exclusive and so this structure is
+/// modelled as an enum.
 ///
 /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#link-object>.
+///
+/// [runtime expression]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#runtime-expressions
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
 #[serde(untagged)]
 pub enum Link {
     /// A relative or absolute reference to an OAS operation.
-    ///
-    /// This field is mutually exclusive of the `operationId` field, and MUST point to an
-    /// [Operation Object]. Relative `operationRef` values MAY be used to locate an existing
-    /// [Operation Object] in the OpenAPI definition.
-    ///
-    /// [Operation Object]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object
     Ref {
+        /// A relative or absolute reference to an OAS operation.
+        ///
+        /// This field is mutually exclusive of the `operationId` field, and MUST point to an
+        /// [Operation Object]. Relative `operationRef` values MAY be used to locate an existing
+        /// [Operation Object] in the OpenAPI definition.
+        ///
+        /// [Operation Object]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object
         #[serde(rename = "operationRef")]
         operation_ref: String,
 
+        /// A map representing parameters to pass to an operation.
+        ///
+        /// The key is the parameter name to be used, whereas the value can be a constant or an
+        /// expression to be evaluated and passed to the linked operation. The parameter name can be
+        /// qualified using the [parameter location] `[{in}.]{name}` for operations that use the
+        /// same parameter name in different locations (e.g. path.id).
+        ///
+        /// [parameter location]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn
+        //
         // FIXME: Implement
-        // /// A map representing parameters to pass to an operation as specified with `operationId`
-        // /// or identified via `operationRef`. The key is the parameter name to be used, whereas
-        // /// the value can be a constant or an expression to be evaluated and passed to the
-        // /// linked operation. The parameter name can be qualified using the
-        // /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn)
-        // /// `[{in}.]{name}` for operations that use the same parameter name in different
-        // /// locations (e.g. path.id).
         // parameters: BTreeMap<String, Any | {expression}>,
         //
         #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
@@ -54,6 +60,7 @@ pub enum Link {
         // request_body: Any | {expression}
         //
         /// A description of the link.
+        ///
         /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
         /// representation.
         #[serde(skip_serializing_if = "Option::is_none")]
@@ -72,22 +79,23 @@ pub enum Link {
         extensions: BTreeMap<String, serde_json::Value>,
     },
 
-    /// The name of an _existing_, resolvable OAS operation, as defined with a unique
-    /// `operationId`.
-    ///
-    /// This field is mutually exclusive of the `operationRef` field.
+    /// The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.
     Id {
+        /// The name of an _existing_, resolvable OAS operation, as defined with a unique
+        /// `operationId`.
         #[serde(rename = "operationId")]
         operation_id: String,
 
+        /// A map representing parameters to pass to an operation.
+        ///
+        /// The key is the parameter name to be used, whereas the value can be a constant or an
+        /// expression to be evaluated and passed to the linked operation. The parameter name can be
+        /// qualified using the [parameter location] `[{in}.]{name}` for operations that use the
+        /// same parameter name in different locations (e.g. path.id).
+        ///
+        /// [parameter location]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn
+        //
         // FIXME: Implement
-        // /// A map representing parameters to pass to an operation as specified with `operationId`
-        // /// or identified via `operationRef`. The key is the parameter name to be used, whereas
-        // /// the value can be a constant or an expression to be evaluated and passed to the
-        // /// linked operation. The parameter name can be qualified using the
-        // /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn)
-        // /// `[{in}.]{name}` for operations that use the same parameter name in different
-        // /// locations (e.g. path.id).
         // parameters: BTreeMap<String, Any | {expression}>,
         //
         #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]

crates/oas3/src/spec/media_type.rs

@@ -29,6 +29,7 @@ pub struct MediaType {
 }
 
 impl MediaType {
+    /// Resolves and returns the JSON schema definition for this media type.
     pub fn schema(&self, spec: &Spec) -> Result<ObjectSchema, Error> {
         self.schema
             .as_ref()
@@ -37,6 +38,9 @@ impl MediaType {
             .map_err(Error::Ref)
     }
 
+    /// Resolves and returns the provided examples for this media type.
+    ///
+    /// Also see [`MediaTypeExamples::resolve_all()`].
     pub fn examples(&self, spec: &Spec) -> BTreeMap<String, Example> {
         self.examples
             .as_ref()

crates/oas3/src/spec/media_type_examples.rs

@@ -5,6 +5,7 @@ use serde::{Deserialize, Serialize};
 
 use super::{Example, ObjectOrReference, Spec};
 
+/// Examples for a media type.
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(untagged)]
 pub enum MediaTypeExamples {

crates/oas3/src/spec/parameter.rs

@@ -7,6 +7,7 @@ use super::{
     RefType, Spec,
 };
 
+/// Parameter location.
 #[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub enum ParameterIn {
@@ -34,6 +35,7 @@ pub enum ParameterIn {
     Cookie,
 }
 
+/// Parameter style.
 #[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub enum ParameterStyle {

crates/oas3/src/spec/ref.rs

@@ -12,20 +12,26 @@ static RE_REF: Lazy<Regex> = Lazy::new(|| {
     Regex::new("^(?P<source>[^#]*)#/components/(?P<type>[^/]+)/(?P<name>.+)$").unwrap()
 });
 
+/// Container for a type of OpenAPI object, or a reference to one.
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(untagged)]
 pub enum ObjectOrReference<T> {
+    /// Object reference.
     Ref {
+        /// Path, file reference, or URL pointing to object.
         #[serde(rename = "$ref")]
         ref_path: String,
     },
+
+    /// Inline object.
     Object(T),
 }
 
 impl<T> ObjectOrReference<T>
 where
     T: FromRef,
 {
+    /// Resolves the object (if needed) from the given `spec` and returns it.
     pub fn resolve(&self, spec: &Spec) -> Result<T, RefError> {
         match self {
             Self::Object(component) => Ok(component.clone()),
@@ -34,29 +40,50 @@ where
     }
 }
 
+/// Object reference error.
 #[derive(Clone, Debug, PartialEq, Display, Error)]
 pub enum RefError {
+    /// Referenced object has unknown type.
     #[display("Invalid type: {}", _0)]
-    InvalidType(#[error(not(source))] String),
+    UnknownType(#[error(not(source))] String),
 
+    /// Referenced object was not of expected type.
     #[display("Mismatched type: cannot reference a {} as a {}", _0, _1)]
     MismatchedType(RefType, RefType),
 
-    // TODO: use some kind of path structure
+    /// Reference path points outside the given spec file.
     #[display("Unresolvable path: {}", _0)]
-    Unresolvable(#[error(not(source))] String),
+    Unresolvable(#[error(not(source))] String), // TODO: use some kind of path structure
 }
 
-#[derive(Copy, Clone, Debug, PartialEq, Display)]
+/// Component type of a reference.
+#[derive(Debug, Clone, Copy, PartialEq, Display)]
 pub enum RefType {
+    /// Schema component type.
     Schema,
+
+    /// Response component type.
     Response,
+
+    /// Parameter component type.
     Parameter,
+
+    /// Example component type.
     Example,
+
+    /// Request body component type.
     RequestBody,
+
+    /// Header component type.
     Header,
+
+    /// Security scheme component type.
     SecurityScheme,
+
+    /// Link component type.
     Link,
+
+    /// Callback component type.
     Callback,
 }
 
@@ -74,15 +101,21 @@ impl FromStr for RefType {
             "securitySchemes" => Self::SecurityScheme,
             "links" => Self::Link,
             "callbacks" => Self::Callback,
-            typ => return Err(RefError::InvalidType(typ.to_owned())),
+            typ => return Err(RefError::UnknownType(typ.to_owned())),
         })
     }
 }
 
+/// Parsed reference path.
 #[derive(Debug, Clone)]
 pub struct Ref {
+    /// Source file of the object being references.
     pub source: String,
+
+    /// Type of object being referenced.
     pub kind: RefType,
+
+    /// Name of object being referenced.
     pub name: String,
 }
 
@@ -102,6 +135,10 @@ impl FromStr for Ref {
     }
 }
 
+/// Find an object from a reference path (`$ref`).
+///
+/// Implemented for object types which can be shared via a spec's `components` object.
 pub trait FromRef: Clone {
+    /// Finds an object in `spec` using the given `path`.
     fn from_ref(spec: &Spec, path: &str) -> Result<Self, RefError>;
 }