docs: document security scheme fields

Author: robjtede

crates/oas3/src/spec/security_scheme.rs

@@ -16,61 +16,86 @@ use super::Flows;
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(tag = "type")]
 pub enum SecurityScheme {
+    /// API key authentication.
     #[serde(rename = "apiKey")]
     ApiKey {
-        /// A description for security scheme.
+        /// Description for security scheme.
         ///
-        /// CommonMark syntax MAY be used for rich text representation.
+        /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
+        /// representation.
         #[serde(skip_serializing_if = "Option::is_none")]
         description: Option<String>,
 
+        /// The name of the header, query or cookie parameter to be used.
         name: String,
 
+        /// The location of the API key. Valid values are `"query"`, `"header"`, or `"cookie"`.
         #[serde(rename = "in")]
         location: String,
     },
 
+    /// HTTP authentication.
     #[serde(rename = "http")]
     Http {
-        /// A description for security scheme.
+        /// Description for security scheme.
         ///
-        /// CommonMark syntax MAY be used for rich text representation.
+        /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
+        /// representation.
         #[serde(skip_serializing_if = "Option::is_none")]
         description: Option<String>,
 
+        /// Name of the HTTP Authorization scheme to be used in the Authorization header as defined
+        /// in RFC 7235.
+        ///
+        /// The values used SHOULD be registered in the IANA Authentication Scheme registry.
         scheme: String,
+
+        /// A hint to the client to identify how the bearer token is formatted.
+        ///
+        /// Bearer tokens are usually generated by an authorization server, so this information is
+        /// primarily for documentation purposes.
         #[serde(rename = "bearerFormat")]
         bearer_format: Option<String>,
     },
 
+    /// OAuth2 authentication.
     #[serde(rename = "oauth2")]
     OAuth2 {
-        /// A description for security scheme.
+        /// Description for security scheme.
         ///
-        /// CommonMark syntax MAY be used for rich text representation.
+        /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
+        /// representation.
         #[serde(skip_serializing_if = "Option::is_none")]
         description: Option<String>,
 
+        /// An object containing configuration information for the flow types supported.
         flows: Flows,
     },
 
+    /// OpenID Connect authentication.
     #[serde(rename = "openIdConnect")]
     OpenIdConnect {
-        /// A description for security scheme.
+        /// Description for security scheme.
         ///
-        /// CommonMark syntax MAY be used for rich text representation.
+        /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
+        /// representation.
         #[serde(skip_serializing_if = "Option::is_none")]
         description: Option<String>,
 
+        /// OpenID Connect URL to discover OAuth2 configuration values.
+        ///
+        /// The OpenID Connect standard requires the use of TLS.
         #[serde(rename = "openIdConnectUrl")]
         open_id_connect_url: String,
     },
 
+    /// Mutual TLS authentication.
     #[serde(rename = "mutualTLS")]
     MutualTls {
-        /// A description for security scheme.
+        /// Description for security scheme.
         ///
-        /// CommonMark syntax MAY be used for rich text representation.
+        /// [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text
+        /// representation.
         #[serde(skip_serializing_if = "Option::is_none")]
         description: Option<String>,
     },