[hermes] Finish up docs (#1002)

* docs

* stuff

* comment

hermes/Cargo.lock

@@ -1764,7 +1764,7 @@ checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
 
 [[package]]
 name = "hermes"
-version = "0.1.6"
+version = "0.1.7"
 dependencies = [
  "anyhow",
  "axum",

hermes/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name                   = "hermes"
-version                = "0.1.6"
+version                = "0.1.7"
 edition                = "2021"
 
 [dependencies]

hermes/src/api/rest.rs

@@ -5,6 +5,7 @@ use {
         RpcPriceIdentifier,
     },
     crate::{
+        doc_examples,
         impl_deserialize_for_hex_string_wrapper,
         store::types::{
             RequestTime,
@@ -111,7 +112,7 @@ pub struct LatestVaasQueryParams {
   get,
   path = "/api/latest_vaas",
   responses(
-    (status = 200, description = "VAAs retrieved successfully", body = Vec<String>)
+    (status = 200, description = "VAAs retrieved successfully", body = Vec<String>, example=json!([doc_examples::vaa_example()]))
   ),
   params(
     LatestVaasQueryParams
@@ -199,7 +200,7 @@ pub struct GetPriceFeedQueryParams {
     id:           PriceIdInput,
     /// The unix timestamp in seconds. This endpoint will return the first update
     /// whose publish_time is >= the provided value.
-    #[param(value_type = i64, example=1690576641)]
+    #[param(value_type = i64, example=doc_examples::timestamp_example)]
     publish_time: UnixTimestamp,
     /// If true, include the `metadata` field in the response with additional metadata about
     /// the price update.
@@ -264,6 +265,7 @@ pub struct GetVaaQueryParams {
 #[derive(Debug, serde::Serialize, ToSchema)]
 pub struct GetVaaResponse {
     /// The VAA binary represented as a base64 string.
+    #[schema(example=doc_examples::vaa_example)]
     vaa:          String,
     #[serde(rename = "publishTime")]
     #[schema(value_type = i64, example=1690576641)]

hermes/src/api/types.rs

@@ -1,5 +1,6 @@
 use {
     crate::{
+        doc_examples,
         impl_deserialize_for_hex_string_wrapper,
         store::types::{
             PriceFeedUpdate,
@@ -19,23 +20,21 @@ use {
         Deref,
         DerefMut,
     },
-    hex::FromHexError,
     pyth_sdk::PriceIdentifier,
     utoipa::ToSchema,
     wormhole_sdk::Chain,
 };
 
-
 /// A price id is a 32-byte hex string, optionally prefixed with "0x".
 /// Price ids are case insensitive.
 ///
 /// Examples:
-/// * 0x63f341689d98a12ef60a5cff1d7f85c70a9e17bf1575f0e7c0b2512d48b1c8b3
+/// * 0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43
-/// * 63f341689d98a12ef60a5cff1d7f85c70a9e17bf1575f0e7c0b2512d48b1c8b3
+/// * e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43
 ///
 /// See https://pyth.network/developers/price-feed-ids for a list of all price feed ids.
 #[derive(Debug, Clone, Deref, DerefMut, ToSchema)]
-#[schema(value_type=String, example="63f341689d98a12ef60a5cff1d7f85c70a9e17bf1575f0e7c0b2512d48b1c8b3")]
+#[schema(value_type=String, example=doc_examples::price_feed_id_example)]
 pub struct PriceIdInput([u8; 32]);
 // TODO: Use const generics instead of macro.
 impl_deserialize_for_hex_string_wrapper!(PriceIdInput, 32);
@@ -54,7 +53,7 @@ pub struct RpcPriceFeedMetadata {
     pub slot:                       Slot,
     #[schema(example = 26)]
     pub emitter_chain:              u16,
-    #[schema(value_type = i64, example=1690576641)]
+    #[schema(value_type = i64, example=doc_examples::timestamp_example)]
     pub price_service_receive_time: UnixTimestamp,
 }
 
@@ -67,7 +66,7 @@ pub struct RpcPriceFeed {
     pub metadata:  Option<RpcPriceFeedMetadata>,
     /// The VAA binary represented as a base64 string.
     #[serde(skip_serializing_if = "Option::is_none")]
-    #[schema(value_type = Option<String>, example="UE5BVQEAAAADuAEAAAADDQC1H7meY5fTed0FsykIb8dt+7nKpbuzfvU2DplDi+dcUl8MC+UIkS65+rkiq+zmNBxE2gaxkBkjdIicZ/fBo+X7AAEqp+WtlWb84np8jJfLpuQ2W+l5KXTigsdAhz5DyVgU3xs+EnaIZxBwcE7EKzjMam+V9rlRy0CGsiQ1kjqqLzfAAQLsoVO0Vu5gVmgc8XGQ7xYhoz36rsBgMjG+e3l/B01esQi/KzPuBf/Ar8Sg5aSEOvEU0muSDb+KIr6d8eEC+FtcAAPZEaBSt4ysXVL84LUcJemQD3SiG30kOfUpF8o7/wI2M2Jf/LyCsbKEQUyLtLbZqnJBSfZJR5AMsrnHDqngMLEGAAY4UDG9GCpRuPvg8hOlsrXuPP3zq7yVPqyG0SG+bNo8rEhP5b1vXlHdG4bZsutX47d5VZ6xnFROKudx3T3/fnWUAQgAU1+kUFc3e0ZZeX1dLRVEryNIVyxMQIcxWwdey+jlIAYowHRM0fJX3Scs80OnT/CERwh5LMlFyU1w578NqxW+AQl2E/9fxjgUTi8crOfDpwsUsmOWw0+Q5OUGhELv/2UZoHAjsaw9OinWUggKACo4SdpPlHYldoWF+J2yGWOW+F4iAQre4c+ocb6a9uSWOnTldFkioqhd9lhmV542+VonCvuy4Tu214NP+2UNd/4Kk3KJCf3iziQJrCBeLi1cLHdLUikgAQtvRFR/nepcF9legl+DywAkUHi5/1MNjlEQvlHyh2XbMiS85yu7/9LgM6Sr+0ukfZY5mSkOcvUkpHn+T+Nw/IrQAQ7lty5luvKUmBpI3ITxSmojJ1aJ0kj/dc0ZcQk+/qo0l0l3/eRLkYjw5j+MZKA8jEubrHzUCke98eSoj8l08+PGAA+DAKNtCwNZe4p6J1Ucod8Lo5RKFfA84CPLVyEzEPQFZ25U9grUK6ilF4GhEia/ndYXLBt3PGW3qa6CBBPM7rH3ABGAyYEtUwzB4CeVedA5o6cKpjRkIebqDNSOqltsr+w7kXdfFVtsK2FMGFZNt5rbpIR+ppztoJ6eOKHmKmi9nQ99ARKkTxRErOs9wJXNHaAuIRV38o1pxRrlQRzGsRuKBqxcQEpC8OPFpyKYcp6iD5l7cO/gRDTamLFyhiUBwKKMP07FAWTEJv8AAAAAABrhAfrtrFhR4yubI7X5QRqMK6xKrj7U3XuBHdGnLqSqcQAAAAAAGp0GAUFVV1YAAAAAAAUYUmIAACcQBsfKUtr4PgZbIXRxRESU79PjE4IBAFUA5i32yLSoX+GmfbRNwS3l2zMPesZrctxliv7fD0pBW0MAAAKqqMJFwAAAAAAqE/NX////+AAAAABkxCb7AAAAAGTEJvoAAAKqIcWxYAAAAAAlR5m4CP/mPsh1IezjYpDlJ4GRb5q4fTs2LjtyO6M0XgVimrIQ4kSh1qg7JKW4gbGkyRntVFR9JO/GNd3FPDit0BK6M+JzXh/h12YNCz9wxlZTvXrNtWNbzqT+91pvl5cphhSPMfAHyEzTPaGR9tKDy9KNu56pmhaY32d2vfEWQmKo22guegeR98oDxs67MmnUraco46a3zEnac2Bm80pasUgMO24=")]
+    #[schema(value_type = Option<String>, example=doc_examples::vaa_example)]
     pub vaa:       Option<Base64String>,
 }
 
@@ -141,7 +140,7 @@ pub struct RpcPrice {
     pub expo:         i32,
     /// When the price was published. The `publish_time` is a unix timestamp, i.e., the number of
     /// seconds since the Unix epoch (00:00:00 UTC on 1 Jan 1970).
-    #[schema(value_type = i64, example=1690576641)]
+    #[schema(value_type = i64, example=doc_examples::timestamp_example)]
     pub publish_time: UnixTimestamp,
 }
 
@@ -163,7 +162,7 @@ pub struct RpcPrice {
     ToSchema,
 )]
 #[repr(C)]
-#[schema(value_type = String, example = "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43")]
+#[schema(value_type = String, example = doc_examples::price_feed_id_example)]
 pub struct RpcPriceIdentifier(#[serde(with = "hex")] [u8; 32]);
 
 impl RpcPriceIdentifier {

hermes/src/doc_examples.rs

@@ -0,0 +1,32 @@
+use crate::store::types::UnixTimestamp;
+
+// Example values for the utoipa API docs.
+// Note that each of these expressions is only evaluated once when the documentation is created,
+// so the examples don't auto-update over time. We may want to adjust these examples for
+// stable/beta in the future so that the example values in the docs work for both hermes and hermes-beta.
+// (Currently all example values are for stable.)
+
+/// Example value for a price feed id
+pub fn price_feed_id_example() -> &'static str {
+    return "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43";
+}
+
+/// Example value for a unix timestamp
+pub fn timestamp_example() -> UnixTimestamp {
+    use std::time::{
+        SystemTime,
+        UNIX_EPOCH,
+    };
+
+    let start = SystemTime::now();
+    let since_the_epoch = start
+        .duration_since(UNIX_EPOCH)
+        .expect("Time went backwards");
+
+    return since_the_epoch.as_secs() as UnixTimestamp;
+}
+
+/// Example value for a VAA
+pub fn vaa_example() -> &'static str {
+    return "UE5BVQEAAAADuAEAAAADDQC1H7meY5fTed0FsykIb8dt+7nKpbuzfvU2DplDi+dcUl8MC+UIkS65+rkiq+zmNBxE2gaxkBkjdIicZ/fBo+X7AAEqp+WtlWb84np8jJfLpuQ2W+l5KXTigsdAhz5DyVgU3xs+EnaIZxBwcE7EKzjMam+V9rlRy0CGsiQ1kjqqLzfAAQLsoVO0Vu5gVmgc8XGQ7xYhoz36rsBgMjG+e3l/B01esQi/KzPuBf/Ar8Sg5aSEOvEU0muSDb+KIr6d8eEC+FtcAAPZEaBSt4ysXVL84LUcJemQD3SiG30kOfUpF8o7/wI2M2Jf/LyCsbKEQUyLtLbZqnJBSfZJR5AMsrnHDqngMLEGAAY4UDG9GCpRuPvg8hOlsrXuPP3zq7yVPqyG0SG+bNo8rEhP5b1vXlHdG4bZsutX47d5VZ6xnFROKudx3T3/fnWUAQgAU1+kUFc3e0ZZeX1dLRVEryNIVyxMQIcxWwdey+jlIAYowHRM0fJX3Scs80OnT/CERwh5LMlFyU1w578NqxW+AQl2E/9fxjgUTi8crOfDpwsUsmOWw0+Q5OUGhELv/2UZoHAjsaw9OinWUggKACo4SdpPlHYldoWF+J2yGWOW+F4iAQre4c+ocb6a9uSWOnTldFkioqhd9lhmV542+VonCvuy4Tu214NP+2UNd/4Kk3KJCf3iziQJrCBeLi1cLHdLUikgAQtvRFR/nepcF9legl+DywAkUHi5/1MNjlEQvlHyh2XbMiS85yu7/9LgM6Sr+0ukfZY5mSkOcvUkpHn+T+Nw/IrQAQ7lty5luvKUmBpI3ITxSmojJ1aJ0kj/dc0ZcQk+/qo0l0l3/eRLkYjw5j+MZKA8jEubrHzUCke98eSoj8l08+PGAA+DAKNtCwNZe4p6J1Ucod8Lo5RKFfA84CPLVyEzEPQFZ25U9grUK6ilF4GhEia/ndYXLBt3PGW3qa6CBBPM7rH3ABGAyYEtUwzB4CeVedA5o6cKpjRkIebqDNSOqltsr+w7kXdfFVtsK2FMGFZNt5rbpIR+ppztoJ6eOKHmKmi9nQ99ARKkTxRErOs9wJXNHaAuIRV38o1pxRrlQRzGsRuKBqxcQEpC8OPFpyKYcp6iD5l7cO/gRDTamLFyhiUBwKKMP07FAWTEJv8AAAAAABrhAfrtrFhR4yubI7X5QRqMK6xKrj7U3XuBHdGnLqSqcQAAAAAAGp0GAUFVV1YAAAAAAAUYUmIAACcQBsfKUtr4PgZbIXRxRESU79PjE4IBAFUA5i32yLSoX+GmfbRNwS3l2zMPesZrctxliv7fD0pBW0MAAAKqqMJFwAAAAAAqE/NX////+AAAAABkxCb7AAAAAGTEJvoAAAKqIcWxYAAAAAAlR5m4CP/mPsh1IezjYpDlJ4GRb5q4fTs2LjtyO6M0XgVimrIQ4kSh1qg7JKW4gbGkyRntVFR9JO/GNd3FPDit0BK6M+JzXh/h12YNCz9wxlZTvXrNtWNbzqT+91pvl5cphhSPMfAHyEzTPaGR9tKDy9KNu56pmhaY32d2vfEWQmKo22guegeR98oDxs67MmnUraco46a3zEnac2Bm80pasUgMO24=";
+}

hermes/src/main.rs

@@ -10,6 +10,7 @@ use {
 
 mod api;
 mod config;
+mod doc_examples;
 mod macros;
 mod network;
 mod store;