docs: document oauth flows fields

Author: robjtede

.vscode/settings.json

@@ -3,6 +3,7 @@
         "btreemap",
         "deque",
         "deserializable",
+        "docsrs",
         "dotenv",
         "indoc",
         "ints",

Cargo.toml

@@ -13,6 +13,7 @@ rust_2018_idioms = "deny"
 nonstandard_style = "deny"
 future_incompatible = "deny"
 missing_debug_implementations = { level = "warn", priority = -1 }
+missing_docs = { level = "warn", priority = -1 }
 
 [workspace.dependencies]
 assert_matches = "1"

crates/oas3/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Expose the `spec::ClientCredentialsFlow::token_url` field.
+
 ## 0.12.1
 
 - No significant changes since `0.12.0`.

crates/oas3/src/lib.rs

@@ -14,6 +14,8 @@
 //!
 //! [OpenAPI v3.1]: https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md
 
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 use std::{fs::File, io::Read, path::Path};
 
 mod error;

crates/oas3/src/spec/flows.rs

@@ -3,23 +3,37 @@ use std::collections::BTreeMap;
 use serde::{Deserialize, Serialize};
 use url::Url;
 
+use super::spec_extensions;
+
 /// Allows configuration of the supported OAuth Flows.
 ///
 /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#oauth-flows-object>.
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct Flows {
+    /// Configuration for the OAuth Implicit flow.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub implicit: Option<ImplicitFlow>,
 
+    /// Configuration for the OAuth Resource Owner Password flow.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub password: Option<PasswordFlow>,
 
+    /// Configuration for the OAuth Client Credentials flow.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub client_credentials: Option<ClientCredentialsFlow>,
 
+    /// Configuration for the OAuth Authorization Code flow.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub authorization_code: Option<AuthorizationCodeFlow>,
+
+    /// Specification extensions.
+    ///
+    /// Only "x-" prefixed keys are collected, and the prefix is stripped.
+    ///
+    /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#specification-extensions>.
+    #[serde(flatten, with = "spec_extensions")]
+    pub extensions: BTreeMap<String, serde_json::Value>,
 }
 
 /// Configuration details for a implicit OAuth Flow.
@@ -28,12 +42,30 @@ pub struct Flows {
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct ImplicitFlow {
+    /// The authorization URL to be used for this flow.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     pub authorization_url: Url,
 
+    /// The URL to be used for obtaining refresh tokens.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub refresh_url: Option<Url>,
 
+    /// The available scopes for the OAuth2 security scheme.
+    ///
+    /// A map between the scope name and a short description for it. The map MAY be empty.
+    #[serde(default)]
     pub scopes: BTreeMap<String, String>,
+
+    /// Specification extensions.
+    ///
+    /// Only "x-" prefixed keys are collected, and the prefix is stripped.
+    ///
+    /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#specification-extensions>.
+    #[serde(flatten, with = "spec_extensions")]
+    pub extensions: BTreeMap<String, serde_json::Value>,
 }
 
 /// Configuration details for a password OAuth Flow.
@@ -42,11 +74,21 @@ pub struct ImplicitFlow {
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct PasswordFlow {
-    token_url: Url,
+    /// The token URL to be used for this flow.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+    pub token_url: Url,
 
+    /// The URL to be used for obtaining refresh tokens.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub refresh_url: Option<Url>,
 
+    /// The available scopes for the OAuth2 security scheme.
+    ///
+    /// A map between the scope name and a short description for it. The map MAY be empty.
+    #[serde(default)]
     pub scopes: BTreeMap<String, String>,
 }
 
@@ -56,11 +98,21 @@ pub struct PasswordFlow {
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct ClientCredentialsFlow {
-    token_url: Url,
+    /// The token URL to be used for this flow.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+    pub token_url: Url,
 
+    /// The URL to be used for obtaining refresh tokens.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub refresh_url: Option<Url>,
 
+    /// The available scopes for the OAuth2 security scheme.
+    ///
+    /// A map between the scope name and a short description for it. The map MAY be empty.
+    #[serde(default)]
     pub scopes: BTreeMap<String, String>,
 }
 
@@ -70,12 +122,26 @@ pub struct ClientCredentialsFlow {
 #[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct AuthorizationCodeFlow {
+    /// The authorization URL to be used for this flow.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     pub authorization_url: Url,
+
+    /// The token URL to be used for this flow.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     pub token_url: Url,
 
+    /// The URL to be used for obtaining refresh tokens.
+    ///
+    /// This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub refresh_url: Option<Url>,
 
+    /// The available scopes for the OAuth2 security scheme.
+    ///
+    /// A map between the scope name and a short description for it. The map MAY be empty.
+    #[serde(default)]
     pub scopes: BTreeMap<String, String>,
 }