fix api lint errors

catalyst-gateway/bin/src/service/api/documents/post_document_index_query/query_filter.rs

@@ -5,8 +5,9 @@
 
 use poem_openapi::{types::Example, NewType, Object};
 
+use super::common::types::document::ver::EqOrRangedVerDocumented;
 use crate::service::common::types::document::{
-    doc_ref::IdAndVerRef, doc_type::DocumentType, id::EqOrRangedId, ver::EqOrRangedVer,
+    doc_ref::IdAndVerRefDocumented, doc_type::DocumentType, id::EqOrRangedIdDocumented,
 };
 
 /// Query Filter for the generation of a signed document index.
@@ -31,13 +32,13 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// Either an absolute single Document ID or a range of
     /// [Document IDs](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#id)
     #[oai(skip_serializing_if_is_none)]
-    id: Option<EqOrRangedId>,
+    id: Option<EqOrRangedIdDocumented>,
     /// ## Document Version
     ///
     /// Either an absolute single Document Version or a range of
     /// [Document Versions](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#ver)
     #[oai(skip_serializing_if_is_none)]
-    ver: Option<EqOrRangedVer>,
+    ver: Option<EqOrRangedVerDocumented>,
     /// ## Document Reference
     ///
     /// A [reference](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/meta/#ref-document-reference)
@@ -49,7 +50,7 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// The kind of document that the reference refers to is defined by the
     /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/)
     #[oai(rename = "ref", skip_serializing_if_is_none)]
-    doc_ref: Option<IdAndVerRef>,
+    doc_ref: Option<IdAndVerRefDocumented>,
     /// ## Document Template
     ///
     /// Documents that are created based on a template include the
@@ -64,7 +65,7 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// however, it will always be a template type document that matches the document
     /// itself.
     #[oai(skip_serializing_if_is_none)]
-    template: Option<IdAndVerRef>,
+    template: Option<IdAndVerRefDocumented>,
     /// ## Document Reply
     ///
     /// This is a
@@ -79,7 +80,7 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// The kind of document that the reference refers to is defined by the
     /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
     #[oai(skip_serializing_if_is_none)]
-    reply: Option<IdAndVerRef>,
+    reply: Option<IdAndVerRefDocumented>,
     /// ## Brand
     ///
     /// This is a
@@ -93,7 +94,7 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// Whether a Document Type has a brand reference is defined by its
     /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
     #[oai(skip_serializing_if_is_none)]
-    brand: Option<IdAndVerRef>,
+    brand: Option<IdAndVerRefDocumented>,
     /// ## Campaign
     ///
     /// This is a
@@ -107,7 +108,7 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// Whether a Document Type has a campaign reference is defined by its
     /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
     #[oai(skip_serializing_if_is_none)]
-    campaign: Option<IdAndVerRef>,
+    campaign: Option<IdAndVerRefDocumented>,
     /// ## Category
     ///
     /// This is a
@@ -121,16 +122,18 @@ pub(crate) struct DocumentIndexQueryFilter {
     /// Whether a Document Type has a category reference is defined by its
     /// [Document Type](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/).
     #[oai(skip_serializing_if_is_none)]
-    category: Option<IdAndVerRef>,
+    category: Option<IdAndVerRefDocumented>,
 }
 
 impl Example for DocumentIndexQueryFilter {
     fn example() -> Self {
         Self {
             doc_type: Some(DocumentType::example()),
-            id: Some(EqOrRangedId::example()),
-            ver: Some(EqOrRangedVer::example()),
-            doc_ref: Some(IdAndVerRef::example()),
+            id: Some(EqOrRangedIdDocumented::example()),
+            ver: Some(EqOrRangedVerDocumented::example()),
+            doc_ref: Some(IdAndVerRefDocumented::example_id_ref()),
+            template: Some(IdAndVerRefDocumented::example_id_and_ver_ref()),
+            reply: Some(IdAndVerRefDocumented::example()),
             ..Default::default()
         }
     }

catalyst-gateway/bin/src/service/common/types/document/doc_ref.rs

@@ -6,21 +6,35 @@
 use poem_openapi::{types::Example, NewType, Object, Union};
 
 use super::{
-    id::{DocumentId, EqOrRangedId},
-    ver::{DocumentVer, EqOrRangedVer},
+    id::{DocumentId, EqOrRangedIdDocumented},
+    ver::{DocumentVer, EqOrRangedVerDocumented},
 };
 
 #[derive(Object, Debug, PartialEq)]
+#[oai(example = true)]
 /// A Reference to a Document ID/s and their version/s.
 pub(crate) struct IdRefOnly {
     /// Document ID, or range of Document IDs
-    id: EqOrRangedId,
+    id: EqOrRangedIdDocumented,
+}
+
+impl Example for IdRefOnly {
+    fn example() -> Self {
+        Self {
+            id: EqOrRangedIdDocumented::example(),
+        }
+    }
 }
 
 // Note: We need to do this, because POEM doesn't give us a way to set `"title"` for the
 // openapi docs on an object.
 #[derive(NewType, Debug, PartialEq)]
-#[oai(from_multipart = false, from_parameter = false, to_header = false)]
+#[oai(
+    from_multipart = false,
+    from_parameter = false,
+    to_header = false,
+    example = true
+)]
 /// Document ID Reference
 ///
 /// A Reference to the Document ID Only.
@@ -29,21 +43,37 @@ pub(crate) struct IdRefOnly {
 /// The Document Version is not considered, and will match any version.
 pub(crate) struct IdRefOnlyDocumented(pub(crate) IdRefOnly);
 
+impl Example for IdRefOnlyDocumented {
+    fn example() -> Self {
+        Self(IdRefOnly::example())
+    }
+}
+
 #[derive(Object, Debug, PartialEq)]
 /// A Reference to a Document ID/s and their version/s.
 pub(crate) struct VerRefWithOptionalId {
     /// Document ID, or range of Document IDs
     #[oai(skip_serializing_if_is_none)]
-    id: Option<EqOrRangedId>,
+    id: Option<EqOrRangedIdDocumented>,
     /// Document Version, or Range of Document Versions
-    ver: EqOrRangedVer,
+    ver: EqOrRangedVerDocumented,
 }
 
 impl Example for VerRefWithOptionalId {
     fn example() -> Self {
         Self {
             id: None,
-            ver: EqOrRangedVer::example(),
+            ver: EqOrRangedVerDocumented::example(),
+        }
+    }
+}
+
+impl VerRefWithOptionalId {
+    /// Returns an example of this type that includes both an `id` and `ver`
+    fn example_id_and_ver_ref() -> Self {
+        Self {
+            id: Some(EqOrRangedIdDocumented::example()),
+            ver: EqOrRangedVerDocumented::example(),
         }
     }
 }
@@ -73,22 +103,40 @@ impl Example for VerRefWithOptionalIdDocumented {
     }
 }
 
+impl VerRefWithOptionalIdDocumented {
+    /// Returns an example of this type that includes both an `id` and `ver`
+    fn example_id_and_ver_ref() -> Self {
+        Self(VerRefWithOptionalId::example_id_and_ver_ref())
+    }
+}
+
 #[derive(Union, Debug, PartialEq)]
-#[oai(one_of)]
 /// Either a Single Document ID, or a Range of Document IDs
-pub(crate) enum IdAndVerRefInner {
+pub(crate) enum IdAndVerRef {
     /// Document ID Reference ONLY
     IdRefOnly(IdRefOnlyDocumented),
     /// Version Reference with Optional Document ID Reference
     IdAndVerRef(VerRefWithOptionalIdDocumented),
 }
 
-impl Example for IdAndVerRefInner {
+impl Example for IdAndVerRef {
     fn example() -> Self {
         Self::IdAndVerRef(VerRefWithOptionalIdDocumented::example())
     }
 }
 
+impl IdAndVerRef {
+    /// Returns an example of this type that only an `id`
+    fn example_id_ref() -> Self {
+        Self::IdRefOnly(IdRefOnlyDocumented::example())
+    }
+
+    /// Returns an example of this type that includes both an `id` and `ver`
+    fn example_id_and_ver_ref() -> Self {
+        Self::IdAndVerRef(VerRefWithOptionalIdDocumented::example_id_and_ver_ref())
+    }
+}
+
 // Note: We need to do this, because POEM doesn't give us a way to set `"title"` for the
 // openapi docs on an object.
 #[derive(NewType, Debug, PartialEq)]
@@ -105,11 +153,23 @@ impl Example for IdAndVerRefInner {
 /// to another Documents ID and/or Version.
 ///
 /// *Note: at least one of `id` or `ver` must be defined.*
-pub(crate) struct IdAndVerRef(pub(crate) IdAndVerRefInner);
+pub(crate) struct IdAndVerRefDocumented(pub(crate) IdAndVerRef);
 
-impl Example for IdAndVerRef {
+impl Example for IdAndVerRefDocumented {
     fn example() -> Self {
-        Self(IdAndVerRefInner::example())
+        Self(IdAndVerRef::example())
+    }
+}
+
+impl IdAndVerRefDocumented {
+    /// Returns an example of this type that includes only an `id`
+    pub(crate) fn example_id_ref() -> Self {
+        Self(IdAndVerRef::example_id_ref())
+    }
+
+    /// Returns an example of this type that includes both an `id` and `ver`
+    pub(crate) fn example_id_and_ver_ref() -> Self {
+        Self(IdAndVerRef::example_id_and_ver_ref())
     }
 }
 

catalyst-gateway/bin/src/service/common/types/document/id.rs

@@ -27,6 +27,10 @@ const DESCRIPTION: &str = "Unique [Document ID](https://input-output-hk.github.i
 UUIDv7 Formatted 128bit value.";
 /// Example.
 const EXAMPLE: &str = "01944e87-e68c-7f22-9df1-816863cfa5ff";
+/// Example minimum - Timestamp retained, random value set to all `0`
+const EXAMPLE_MIN: &str = "01944e87-e68c-7000-8000-000000000000";
+/// Example maximum - Timestamp retained, random value set to all `f`
+const EXAMPLE_MAX: &str = "01944e87-e68c-7fff-bfff-ffffffffffff";
 /// External Documentation URI
 const URI: &str =
     "https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#id";
@@ -73,6 +77,18 @@ impl Example for DocumentId {
     }
 }
 
+impl DocumentId {
+    /// An example of a minimum Document ID when specifying ranges
+    fn example_min() -> Self {
+        Self(EXAMPLE_MIN.to_owned())
+    }
+
+    /// An example of a maximum Document ID when specifying ranges
+    fn example_max() -> Self {
+        Self(EXAMPLE_MAX.to_owned())
+    }
+}
+
 impl TryFrom<&str> for DocumentId {
     type Error = anyhow::Error;
 
@@ -99,37 +115,93 @@ impl From<uuidv7::UUIDv7> for DocumentId {
 }
 
 #[derive(Object, Debug, PartialEq)]
+#[oai(example = true)]
 /// A range of Document IDs.
-pub(crate) struct IdRangeInner {
+pub(crate) struct IdRange {
     /// Minimum Document ID to find (inclusive)
     min: DocumentId,
     /// Maximum Document ID to find (inclusive)
     max: DocumentId,
 }
 
+impl Example for IdRange {
+    fn example() -> Self {
+        Self {
+            min: DocumentId::example_min(),
+            max: DocumentId::example_max(),
+        }
+    }
+}
+
+#[derive(Object, Debug, PartialEq)]
+#[oai(example = true)]
+/// A single Document IDs.
+pub(crate) struct IdEq {
+    /// The exact Document ID to match against.
+    eq: DocumentId,
+}
+
+impl Example for IdEq {
+    fn example() -> Self {
+        Self {
+            eq: DocumentId::example(),
+        }
+    }
+}
+
 // Note: We need to do this, because POEM doesn't give us a way to set `"title"` for the
 // openapi docs on an object.
 #[derive(NewType, Debug, PartialEq)]
-#[oai(from_multipart = false, from_parameter = false, to_header = false)]
+#[oai(
+    from_multipart = false,
+    from_parameter = false,
+    to_header = false,
+    example = true
+)]
+/// ID Equals
+///
+/// A specific single
+/// [Document ID](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#id).
+pub(crate) struct IdEqDocumented(IdEq);
+impl Example for IdEqDocumented {
+    fn example() -> Self {
+        Self(IdEq::example())
+    }
+}
+
+// Note: We need to do this, because POEM doesn't give us a way to set `"title"` for the
+// openapi docs on an object.
+#[derive(NewType, Debug, PartialEq)]
+#[oai(
+    from_multipart = false,
+    from_parameter = false,
+    to_header = false,
+    example = true
+)]
 /// ID Range
 ///
 /// A range of
 /// [Document IDs](https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/#id).
-pub(crate) struct IdRange(IdRangeInner);
+pub(crate) struct IdRangeDocumented(IdRange);
+impl Example for IdRangeDocumented {
+    fn example() -> Self {
+        Self(IdRange::example())
+    }
+}
 
 #[derive(Union, Debug, PartialEq)]
 #[oai(one_of)]
 /// Either a Single Document ID, or a Range of Document IDs
-pub(crate) enum EqOrRangedIdInner {
+pub(crate) enum EqOrRangedId {
     /// This exact Document ID
-    Eq(DocumentId),
+    Eq(IdEqDocumented),
     /// Document IDs in this range
-    Range(IdRange),
+    Range(IdRangeDocumented),
 }
 
-impl Example for EqOrRangedIdInner {
+impl Example for EqOrRangedId {
     fn example() -> Self {
-        Self::Eq(DocumentId::example())
+        Self::Eq(IdEqDocumented::example())
     }
 }
 
@@ -143,10 +215,10 @@ impl Example for EqOrRangedIdInner {
 /// Document ID Selector
 ///
 /// Either a absolute single Document ID or a range of Document IDs
-pub(crate) struct EqOrRangedId(EqOrRangedIdInner);
+pub(crate) struct EqOrRangedIdDocumented(pub(crate) EqOrRangedId);
 
-impl Example for EqOrRangedId {
+impl Example for EqOrRangedIdDocumented {
     fn example() -> Self {
-        Self(EqOrRangedIdInner::example())
+        Self(EqOrRangedId::example())
     }
 }