Skip to content

Commit 8c8441e

Browse files
committed
docs: document ref fields
1 parent 9af2dc9 commit 8c8441e

File tree

6 files changed

+90
-37
lines changed

6 files changed

+90
-37
lines changed

crates/oas3/CHANGELOG.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44

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

910
## 0.12.1
1011

crates/oas3/src/spec/link.rs

+39-31
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,47 @@ use super::{spec_extensions, Server};
66

77
/// The Link object represents a possible design-time link for a response.
88
///
9-
/// The presence of a link does not guarantee the caller's ability to successfully invoke it,
10-
/// rather it provides a known relationship and traversal mechanism between responses and
11-
/// other operations.
9+
/// The presence of a link does not guarantee the caller's ability to successfully invoke it, rather
10+
/// it provides a known relationship and traversal mechanism between responses and other operations.
1211
///
1312
/// Unlike _dynamic_ links (i.e. links provided *in* the response payload), the OAS linking
1413
/// mechanism does not require link information in the runtime response.
1514
///
16-
/// For computing links, and providing instructions to execute them, a
17-
/// [runtime expression](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#runtimeExpression)
18-
/// is used for accessing values in an operation and using them as parameters while invoking
19-
/// the linked operation.
15+
/// For computing links, and providing instructions to execute them, a [runtime expression] is used
16+
/// for accessing values in an operation and using them as parameters while invoking the linked
17+
/// operation.
18+
///
19+
/// The `operationRef` and `operationId` fields are mutually exclusive and so this structure is
20+
/// modelled as an enum.
2021
///
2122
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#link-object>.
23+
///
24+
/// [runtime expression]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#runtime-expressions
2225
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
2326
#[serde(untagged)]
2427
pub enum Link {
2528
/// A relative or absolute reference to an OAS operation.
26-
///
27-
/// This field is mutually exclusive of the `operationId` field, and MUST point to an
28-
/// [Operation Object]. Relative `operationRef` values MAY be used to locate an existing
29-
/// [Operation Object] in the OpenAPI definition.
30-
///
31-
/// [Operation Object]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object
3229
Ref {
30+
/// A relative or absolute reference to an OAS operation.
31+
///
32+
/// This field is mutually exclusive of the `operationId` field, and MUST point to an
33+
/// [Operation Object]. Relative `operationRef` values MAY be used to locate an existing
34+
/// [Operation Object] in the OpenAPI definition.
35+
///
36+
/// [Operation Object]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object
3337
#[serde(rename = "operationRef")]
3438
operation_ref: String,
3539

40+
/// A map representing parameters to pass to an operation.
41+
///
42+
/// The key is the parameter name to be used, whereas the value can be a constant or an
43+
/// expression to be evaluated and passed to the linked operation. The parameter name can be
44+
/// qualified using the [parameter location] `[{in}.]{name}` for operations that use the
45+
/// same parameter name in different locations (e.g. path.id).
46+
///
47+
/// [parameter location]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn
48+
//
3649
// FIXME: Implement
37-
// /// A map representing parameters to pass to an operation as specified with `operationId`
38-
// /// or identified via `operationRef`. The key is the parameter name to be used, whereas
39-
// /// the value can be a constant or an expression to be evaluated and passed to the
40-
// /// linked operation. The parameter name can be qualified using the
41-
// /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn)
42-
// /// `[{in}.]{name}` for operations that use the same parameter name in different
43-
// /// locations (e.g. path.id).
4450
// parameters: BTreeMap<String, Any | {expression}>,
4551
//
4652
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
@@ -54,6 +60,7 @@ pub enum Link {
5460
// request_body: Any | {expression}
5561
//
5662
/// A description of the link.
63+
///
5764
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
5865
/// representation.
5966
#[serde(skip_serializing_if = "Option::is_none")]
@@ -72,22 +79,23 @@ pub enum Link {
7279
extensions: BTreeMap<String, serde_json::Value>,
7380
},
7481

75-
/// The name of an _existing_, resolvable OAS operation, as defined with a unique
76-
/// `operationId`.
77-
///
78-
/// This field is mutually exclusive of the `operationRef` field.
82+
/// The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.
7983
Id {
84+
/// The name of an _existing_, resolvable OAS operation, as defined with a unique
85+
/// `operationId`.
8086
#[serde(rename = "operationId")]
8187
operation_id: String,
8288

89+
/// A map representing parameters to pass to an operation.
90+
///
91+
/// The key is the parameter name to be used, whereas the value can be a constant or an
92+
/// expression to be evaluated and passed to the linked operation. The parameter name can be
93+
/// qualified using the [parameter location] `[{in}.]{name}` for operations that use the
94+
/// same parameter name in different locations (e.g. path.id).
95+
///
96+
/// [parameter location]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn
97+
//
8398
// FIXME: Implement
84-
// /// A map representing parameters to pass to an operation as specified with `operationId`
85-
// /// or identified via `operationRef`. The key is the parameter name to be used, whereas
86-
// /// the value can be a constant or an expression to be evaluated and passed to the
87-
// /// linked operation. The parameter name can be qualified using the
88-
// /// [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#parameterIn)
89-
// /// `[{in}.]{name}` for operations that use the same parameter name in different
90-
// /// locations (e.g. path.id).
9199
// parameters: BTreeMap<String, Any | {expression}>,
92100
//
93101
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]

crates/oas3/src/spec/media_type.rs

+4
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ pub struct MediaType {
2929
}
3030

3131
impl MediaType {
32+
/// Resolves and returns the JSON schema definition for this media type.
3233
pub fn schema(&self, spec: &Spec) -> Result<ObjectSchema, Error> {
3334
self.schema
3435
.as_ref()
@@ -37,6 +38,9 @@ impl MediaType {
3738
.map_err(Error::Ref)
3839
}
3940

41+
/// Resolves and returns the provided examples for this media type.
42+
///
43+
/// Also see [`MediaTypeExamples::resolve_all()`].
4044
pub fn examples(&self, spec: &Spec) -> BTreeMap<String, Example> {
4145
self.examples
4246
.as_ref()

crates/oas3/src/spec/media_type_examples.rs

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ use serde::{Deserialize, Serialize};
55

66
use super::{Example, ObjectOrReference, Spec};
77

8+
/// Examples for a media type.
89
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
910
#[serde(untagged)]
1011
pub enum MediaTypeExamples {

crates/oas3/src/spec/parameter.rs

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ use super::{
77
RefType, Spec,
88
};
99

10+
/// Parameter location.
1011
#[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize)]
1112
#[serde(rename_all = "camelCase")]
1213
pub enum ParameterIn {
@@ -34,6 +35,7 @@ pub enum ParameterIn {
3435
Cookie,
3536
}
3637

38+
/// Parameter style.
3739
#[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize)]
3840
#[serde(rename_all = "camelCase")]
3941
pub enum ParameterStyle {

crates/oas3/src/spec/ref.rs

+42-5
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,26 @@ static RE_REF: Lazy<Regex> = Lazy::new(|| {
1212
Regex::new("^(?P<source>[^#]*)#/components/(?P<type>[^/]+)/(?P<name>.+)$").unwrap()
1313
});
1414

15+
/// Container for a type of OpenAPI object, or a reference to one.
1516
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
1617
#[serde(untagged)]
1718
pub enum ObjectOrReference<T> {
19+
/// Object reference.
1820
Ref {
21+
/// Path, file reference, or URL pointing to object.
1922
#[serde(rename = "$ref")]
2023
ref_path: String,
2124
},
25+
26+
/// Inline object.
2227
Object(T),
2328
}
2429

2530
impl<T> ObjectOrReference<T>
2631
where
2732
T: FromRef,
2833
{
34+
/// Resolves the object (if needed) from the given `spec` and returns it.
2935
pub fn resolve(&self, spec: &Spec) -> Result<T, RefError> {
3036
match self {
3137
Self::Object(component) => Ok(component.clone()),
@@ -34,29 +40,50 @@ where
3440
}
3541
}
3642

43+
/// Object reference error.
3744
#[derive(Clone, Debug, PartialEq, Display, Error)]
3845
pub enum RefError {
46+
/// Referenced object has unknown type.
3947
#[display("Invalid type: {}", _0)]
40-
InvalidType(#[error(not(source))] String),
48+
UnknownType(#[error(not(source))] String),
4149

50+
/// Referenced object was not of expected type.
4251
#[display("Mismatched type: cannot reference a {} as a {}", _0, _1)]
4352
MismatchedType(RefType, RefType),
4453

45-
// TODO: use some kind of path structure
54+
/// Reference path points outside the given spec file.
4655
#[display("Unresolvable path: {}", _0)]
47-
Unresolvable(#[error(not(source))] String),
56+
Unresolvable(#[error(not(source))] String), // TODO: use some kind of path structure
4857
}
4958

50-
#[derive(Copy, Clone, Debug, PartialEq, Display)]
59+
/// Component type of a reference.
60+
#[derive(Debug, Clone, Copy, PartialEq, Display)]
5161
pub enum RefType {
62+
/// Schema component type.
5263
Schema,
64+
65+
/// Response component type.
5366
Response,
67+
68+
/// Parameter component type.
5469
Parameter,
70+
71+
/// Example component type.
5572
Example,
73+
74+
/// Request body component type.
5675
RequestBody,
76+
77+
/// Header component type.
5778
Header,
79+
80+
/// Security scheme component type.
5881
SecurityScheme,
82+
83+
/// Link component type.
5984
Link,
85+
86+
/// Callback component type.
6087
Callback,
6188
}
6289

@@ -74,15 +101,21 @@ impl FromStr for RefType {
74101
"securitySchemes" => Self::SecurityScheme,
75102
"links" => Self::Link,
76103
"callbacks" => Self::Callback,
77-
typ => return Err(RefError::InvalidType(typ.to_owned())),
104+
typ => return Err(RefError::UnknownType(typ.to_owned())),
78105
})
79106
}
80107
}
81108

109+
/// Parsed reference path.
82110
#[derive(Debug, Clone)]
83111
pub struct Ref {
112+
/// Source file of the object being references.
84113
pub source: String,
114+
115+
/// Type of object being referenced.
85116
pub kind: RefType,
117+
118+
/// Name of object being referenced.
86119
pub name: String,
87120
}
88121

@@ -102,6 +135,10 @@ impl FromStr for Ref {
102135
}
103136
}
104137

138+
/// Find an object from a reference path (`$ref`).
139+
///
140+
/// Implemented for object types which can be shared via a spec's `components` object.
105141
pub trait FromRef: Clone {
142+
/// Finds an object in `spec` using the given `path`.
106143
fn from_ref(spec: &Spec, path: &str) -> Result<Self, RefError>;
107144
}

0 commit comments

Comments
 (0)