From 57a6a58b3907c3a801f4e71e89b4059aae1dba00 Mon Sep 17 00:00:00 2001 From: Adam Leventhal Date: Sun, 22 Oct 2023 17:35:23 -0700 Subject: [PATCH] fill in some missing docs (#84) --- src/media_type.rs | 18 ++++++++++++++++++ src/openapi.rs | 1 + src/parameter.rs | 19 +++++++++++++++++++ src/paths.rs | 8 ++++++++ src/request_body.rs | 1 + src/responses.rs | 4 ++++ src/security_scheme.rs | 6 ++---- 7 files changed, 53 insertions(+), 4 deletions(-) diff --git a/src/media_type.rs b/src/media_type.rs index 76c7ba1..489009a 100644 --- a/src/media_type.rs +++ b/src/media_type.rs @@ -2,16 +2,34 @@ use crate::*; use indexmap::IndexMap; use serde::{Deserialize, Serialize}; +/// Each Media Type Object provides schema and examples for the media type +/// identified by its key. #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)] pub struct MediaType { + /// The schema defining the content of the request, response, or parameter. #[serde(skip_serializing_if = "Option::is_none")] pub schema: Option>, + /// Example of the media type. The example object SHOULD be in the correct + /// format as specified by the media type. The example field is mutually + /// exclusive of the examples field. Furthermore, if referencing a schema + /// which contains an example, the example value SHALL override the example + /// provided by the schema. #[serde(skip_serializing_if = "Option::is_none")] pub example: Option, + /// Examples of the media type. Each example object SHOULD match the media + /// type and specified schema if present. The examples field is mutually + /// exclusive of the example field. Furthermore, if referencing a schema + /// which contains an example, the examples value SHALL override the + /// example provided by the schema. #[serde(default, skip_serializing_if = "IndexMap::is_empty")] pub examples: IndexMap>, + /// A map between a property name and its encoding information. The key, + /// being the property name, MUST exist in the schema as a property. The + /// encoding object SHALL only apply to requestBody objects when the media + /// type is multipart or application/x-www-form-urlencoded. #[serde(default, skip_serializing_if = "IndexMap::is_empty")] pub encoding: IndexMap, + /// Inline extensions to this object. #[serde(flatten, deserialize_with = "crate::util::deserialize_extensions")] pub extensions: IndexMap, diff --git a/src/openapi.rs b/src/openapi.rs index 0e407f4..8282202 100644 --- a/src/openapi.rs +++ b/src/openapi.rs @@ -2,6 +2,7 @@ use crate::*; use indexmap::IndexMap; use serde::{Deserialize, Serialize}; +/// This is the root document object of the OpenAPI document. #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)] pub struct OpenAPI { /// REQUIRED. This string MUST be the semantic version number of the diff --git a/src/parameter.rs b/src/parameter.rs index be81732..df99dbb 100644 --- a/src/parameter.rs +++ b/src/parameter.rs @@ -60,9 +60,12 @@ pub enum ParameterSchemaOrContent { pub type Content = IndexMap; +/// Describes a single operation parameter. #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(tag = "in", rename_all = "camelCase")] pub enum Parameter { + /// Parameters that are appended to the URL. For example, in /items?id=###, + /// the query parameter is id. #[serde(rename_all = "camelCase")] Query { #[serde(flatten)] @@ -87,6 +90,8 @@ pub enum Parameter { #[serde(skip_serializing_if = "Option::is_none")] allow_empty_value: Option, }, + /// Custom headers that are expected as part of the request. Note that + /// RFC7230 states header names are case insensitive. Header { #[serde(flatten)] parameter_data: ParameterData, @@ -97,6 +102,10 @@ pub enum Parameter { #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")] style: HeaderStyle, }, + /// Used together with Path Templating, where the parameter value is + /// actually part of the operation's URL. This does not include the host or + /// base path of the API. For example, in /items/{itemId}, the path + /// parameter is itemId. Path { #[serde(flatten)] parameter_data: ParameterData, @@ -107,6 +116,7 @@ pub enum Parameter { #[serde(default, skip_serializing_if = "SkipSerializeIfDefault::skip")] style: PathStyle, }, + /// Used to pass a specific cookie value to the API. Cookie { #[serde(flatten)] parameter_data: ParameterData, @@ -184,8 +194,11 @@ impl SkipSerializeIfDefault { #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] pub enum PathStyle { + /// Path-style parameters defined by RFC6570. Matrix, + /// Label style parameters defined by RFC6570. Label, + /// Simple style parameters defined by RFC6570. Simple, } @@ -197,9 +210,13 @@ impl Default for PathStyle { #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] pub enum QueryStyle { + /// Form style parameters defined by RFC6570. Form, + /// Space separated array values. SpaceDelimited, + /// Pipe separated array values. PipeDelimited, + /// Provides a simple way of rendering nested objects using form parameters. DeepObject, } @@ -211,6 +228,7 @@ impl Default for QueryStyle { #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] pub enum CookieStyle { + /// Form style parameters defined by RFC6570. Form, } @@ -222,6 +240,7 @@ impl Default for CookieStyle { #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] pub enum HeaderStyle { + /// Simple style parameters defined by RFC6570. Simple, } diff --git a/src/paths.rs b/src/paths.rs index fb20ca6..369a26d 100644 --- a/src/paths.rs +++ b/src/paths.rs @@ -19,20 +19,28 @@ pub struct PathItem { /// this path. CommonMark syntax MAY be used for rich text representation. #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, + /// A definition of a GET operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub get: Option, + /// A definition of a PUT operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub put: Option, + /// A definition of a POST operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub post: Option, + /// A definition of a DELETE operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub delete: Option, + /// A definition of a OPTIONS operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub options: Option, + /// A definition of a HEAD operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub head: Option, + /// A definition of a PATCH operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub patch: Option, + /// A definition of a TRACE operation on this path. #[serde(skip_serializing_if = "Option::is_none")] pub trace: Option, /// An alternative server array to service all operations in this path. diff --git a/src/request_body.rs b/src/request_body.rs index 205ab4c..eb1b26f 100644 --- a/src/request_body.rs +++ b/src/request_body.rs @@ -2,6 +2,7 @@ use crate::*; use indexmap::IndexMap; use serde::{Deserialize, Serialize}; +/// Describes a single request body. #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)] pub struct RequestBody { /// A brief description of the request body. diff --git a/src/responses.rs b/src/responses.rs index 5abbe0e..a90eccd 100644 --- a/src/responses.rs +++ b/src/responses.rs @@ -4,6 +4,8 @@ use crate::*; use indexmap::IndexMap; use serde::{Deserialize, Deserializer, Serialize}; +/// A container for the expected responses of an operation. The container maps +/// a HTTP response code to the expected response. #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)] pub struct Responses { /// The documentation of responses other than the ones declared @@ -32,6 +34,8 @@ pub struct Responses { pub extensions: IndexMap, } +/// Describes a single response from an API Operation, including design-time, +/// static links to operations based on the response. #[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)] pub struct Response { /// REQUIRED. A short description of the response. diff --git a/src/security_scheme.rs b/src/security_scheme.rs index 6a1a567..fc2b001 100644 --- a/src/security_scheme.rs +++ b/src/security_scheme.rs @@ -91,12 +91,10 @@ pub struct OAuth2Flows { /// Configuration for the OAuth Resource Owner Password flow #[serde(default, skip_serializing_if = "Option::is_none")] pub password: Option, - /// Configuration for the OAuth Client Credentials flow. Previously called - /// application in OpenAPI 2.0. + /// Configuration for the OAuth Client Credentials flow. #[serde(default, skip_serializing_if = "Option::is_none")] pub client_credentials: Option, - /// Configuration for the OAuth Authorization Code flow. Previously called - /// accessCode in OpenAPI 2.0. + /// Configuration for the OAuth Authorization Code flow. #[serde(default, skip_serializing_if = "Option::is_none")] pub authorization_code: Option,