Skip to content

Commit 3f27d96

Browse files
committed
docs: document media type examples methods
1 parent 04fba3b commit 3f27d96

File tree

2 files changed

+40
-23
lines changed

2 files changed

+40
-23
lines changed

crates/oas3/src/spec/link.rs

+19-14
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,16 @@ use super::{spec_extensions, Server};
1919
/// the linked operation.
2020
///
2121
/// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#link-object>.
22-
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
22+
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
2323
#[serde(untagged)]
2424
pub enum Link {
25-
/// A relative or absolute reference to an OAS operation. This field is mutually exclusive
26-
/// of the `operationId` field, and MUST point to an
27-
/// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object).
28-
/// Relative `operationRef` values MAY be used to locate an existing
29-
/// [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#operation-object)
30-
/// in the OpenAPI definition.
25+
/// 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
3132
Ref {
3233
#[serde(rename = "operationRef")]
3334
operation_ref: String,
@@ -42,8 +43,7 @@ pub enum Link {
4243
// /// locations (e.g. path.id).
4344
// parameters: BTreeMap<String, Any | {expression}>,
4445
//
45-
#[serde(default)]
46-
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
46+
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
4747
parameters: BTreeMap<String, String>,
4848

4949
// FIXME: Implement
@@ -70,8 +70,11 @@ pub enum Link {
7070
#[serde(flatten, with = "spec_extensions")]
7171
extensions: BTreeMap<String, serde_json::Value>,
7272
},
73+
7374
/// The name of an _existing_, resolvable OAS operation, as defined with a unique
74-
/// `operationId`. This field is mutually exclusive of the `operationRef` field.
75+
/// `operationId`.
76+
///
77+
/// This field is mutually exclusive of the `operationRef` field.
7578
Id {
7679
#[serde(rename = "operationId")]
7780
operation_id: String,
@@ -86,8 +89,7 @@ pub enum Link {
8689
// /// locations (e.g. path.id).
8790
// parameters: BTreeMap<String, Any | {expression}>,
8891
//
89-
#[serde(default)]
90-
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
92+
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
9193
parameters: BTreeMap<String, String>,
9294

9395
// FIXME: Implement
@@ -96,8 +98,11 @@ pub enum Link {
9698
// /// to use as a request body when calling the target operation.
9799
// #[serde(rename = "requestBody")]
98100
// request_body: Any | {expression}
99-
/// A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be
100-
/// used for rich text representation.
101+
//
102+
/// A description of the link.
103+
///
104+
/// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
105+
/// representation.
101106
#[serde(skip_serializing_if = "Option::is_none")]
102107
description: Option<String>,
103108

crates/oas3/src/spec/media_type_examples.rs

+21-9
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,25 @@ use super::{Example, ObjectOrReference, Spec};
88
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
99
#[serde(untagged)]
1010
pub enum MediaTypeExamples {
11-
/// Example of the media type. The example object SHOULD be in the correct format as
12-
/// specified by the media type. The `example` field is mutually exclusive of the
13-
/// `examples` field. Furthermore, if referencing a `schema` which contains an example,
14-
/// the `example` value SHALL override the example provided by the schema.
15-
Example { example: serde_json::Value },
11+
/// Example of the media type.
12+
///
13+
/// The example object SHOULD be in the correct format as specified by the media type. The
14+
/// `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a
15+
/// `schema` which contains an example, the `example` value SHALL override the example provided
16+
/// by the schema.
17+
Example {
18+
/// Example of the media type.
19+
example: serde_json::Value,
20+
},
1621

17-
/// Examples of the media type. Each example object SHOULD match the media type and
18-
/// specified schema if present. The `examples` field is mutually exclusive of
19-
/// the `example` field. Furthermore, if referencing a `schema` which contains an
20-
/// example, the `examples` value SHALL override the example provided by the schema.
22+
/// Examples of the media type.
23+
///
24+
/// Each example object SHOULD match the media type and specified schema if present. The
25+
/// `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a
26+
/// `schema` which contains an example, the `examples` value SHALL override the example provided
27+
/// by the schema.
2128
Examples {
29+
/// Examples of the media type.
2230
examples: BTreeMap<String, ObjectOrReference<Example>>,
2331
},
2432
}
@@ -32,13 +40,17 @@ impl Default for MediaTypeExamples {
3240
}
3341

3442
impl MediaTypeExamples {
43+
/// Returns true if no examples are provided.
3544
pub fn is_empty(&self) -> bool {
3645
match self {
3746
MediaTypeExamples::Example { .. } => false,
3847
MediaTypeExamples::Examples { examples } => examples.is_empty(),
3948
}
4049
}
4150

51+
/// Resolves references and returns a map of provided examples keyed by name.
52+
///
53+
/// If the `example` field is provided, then the map contains one item, keyed as "default".
4254
pub fn resolve_all(&self, spec: &Spec) -> BTreeMap<String, Example> {
4355
match self {
4456
Self::Example { example } => {

0 commit comments

Comments
 (0)