fill in some missing docs (#84)

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<ReferenceOr<Schema>>,
+    /// 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<serde_json::Value>,
+    /// 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<String, ReferenceOr<Example>>,
+    /// 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<String, Encoding>,
+
     /// Inline extensions to this object.
     #[serde(flatten, deserialize_with = "crate::util::deserialize_extensions")]
     pub extensions: IndexMap<String, serde_json::Value>,

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

src/parameter.rs

@@ -60,9 +60,12 @@ pub enum ParameterSchemaOrContent {
 
 pub type Content = IndexMap<String, MediaType>;
 
+/// 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<bool>,
     },
+    /// 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,
 }
 

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<String>,
+    /// A definition of a GET operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub get: Option<Operation>,
+    /// A definition of a PUT operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub put: Option<Operation>,
+    /// A definition of a POST operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub post: Option<Operation>,
+    /// A definition of a DELETE operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub delete: Option<Operation>,
+    /// A definition of a OPTIONS operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub options: Option<Operation>,
+    /// A definition of a HEAD operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub head: Option<Operation>,
+    /// A definition of a PATCH operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub patch: Option<Operation>,
+    /// A definition of a TRACE operation on this path.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub trace: Option<Operation>,
     /// An alternative server array to service all operations in this path.

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.

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<String, serde_json::Value>,
 }
 
+/// 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.

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<PasswordOAuth2Flow>,
-    /// 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<ClientCredentialsOAuth2Flow>,
-    /// 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<AuthorizationCodeOAuth2Flow>,