docs: document contact object

Author: robjtede

crates/oas3/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Add `spec::Contact::validate_email()` method.
 - Expose the `spec::ClientCredentialsFlow::token_url` field.
 - Rename `Error::{SemVerError => Semver}` variant.
 

crates/oas3/src/lib.rs

@@ -21,8 +21,8 @@ use std::{fs::File, io::Read, path::Path};
 mod error;
 pub mod spec;
 
-pub use error::Error;
-pub use spec::Spec;
+pub use self::error::Error;
+pub use self::spec::Spec;
 
 /// Version 3.1.0 of the OpenAPI specification.
 ///

crates/oas3/src/spec/contact.rs

@@ -1,22 +1,34 @@
 use std::collections::BTreeMap;
 
+use derive_more::derive::{Display, Error};
 use serde::{Deserialize, Serialize};
 use url::Url;
 
 use super::spec_extensions;
 
+/// Error raised when contact info contains an email field which is not a valid email.
+#[derive(Debug, Display, Error)]
+#[display("Email address is not valid")]
+#[non_exhaustive]
+pub struct InvalidEmail;
+
 /// Contact information for the exposed API.
 ///
 /// See <https://github.com/OAI/OpenAPI-Specification/blob/HEAD/versions/3.1.0.md#contact-object>.
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
 pub struct Contact {
+    /// Identifying name of the contact person/organization.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub name: Option<String>,
 
+    /// URL pointing to the contact information.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub url: Option<Url>,
 
-    // TODO: Make sure the email is a valid email
+    /// Email address of the contact person/organization.
+    ///
+    /// Use [`validate_email()`](Self::validate_email) after deserializing to check that email
+    /// address provided is valid.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub email: Option<String>,
 
@@ -28,3 +40,18 @@ pub struct Contact {
     #[serde(flatten, with = "spec_extensions")]
     pub extensions: BTreeMap<String, serde_json::Value>,
 }
+
+impl Contact {
+    /// Validates email address field.
+    pub fn validate_email(&self) -> Result<(), InvalidEmail> {
+        let Some(email) = &self.email else {
+            return Ok(());
+        };
+
+        if email.contains("@") {
+            Ok(())
+        } else {
+            Err(InvalidEmail)
+        }
+    }
+}

crates/oas3/src/spec/mod.rs

@@ -149,6 +149,7 @@ pub struct Spec {
 }
 
 impl Spec {
+    /// Validates spec version field.
     pub fn validate_version(&self) -> Result<semver::Version, Error> {
         let spec_version = &self.openapi;
         let sem_ver = semver::Version::parse(spec_version)?;

justfile

@@ -35,7 +35,7 @@ update-readmes:
 [group("lint")]
 clippy:
     cargo clippy --workspace --all-targets --no-default-features
-    cargo clippy --workspace --all-targets --no-default-features --all-features
+    cargo clippy --workspace --all-targets --all-features
     cargo hack --feature-powerset clippy --workspace --all-targets
 
 # Downgrade dev-dependencies necessary to run MSRV checks/tests.