feat(common): Add utoipa attribute macro types (#2000)

* feat(common): Add utoipa attribute macro types

* fix: Move utoipa dependency version into workspace

* fix: Add utoipa secret attributes

---------

Co-authored-by: Niel Drummond <[email protected]>

Author: fussybeaver

Cargo.lock

@@ -84,6 +84,7 @@ tracing-subscriber = { version = "0.3.16", default-features = false, features =
 ] }
 trybuild = "1.0.72"
 typeshare = "1.0.3"
+utoipa = "5"
 url = "2.5.4"
 walkdir = "2.3.3"
 webbrowser = "1.0.1"

Cargo.toml

@@ -21,6 +21,7 @@ serde_json = { workspace = true }
 strum = { workspace = true, features = ["derive"] }
 tracing = { workspace = true, features = ["std"], optional = true }
 typeshare = { workspace = true }
+utoipa = { workspace = true, features = ["chrono"], optional = true }
 zeroize = { workspace = true }
 
 [dev-dependencies]
@@ -35,6 +36,8 @@ axum = ["dep:axum", "dep:tracing"]
 display = ["chrono/clock", "dep:crossterm"]
 tables = ["models", "display", "dep:comfy-table"]
 
+utoipa = ["dep:utoipa"]
+
 # internal / utility features
 integration-tests = []
 

common/Cargo.toml

@@ -1,6 +1,7 @@
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, Debug)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct AddCertificateRequest {
     #[serde(alias = "domain")]
@@ -15,6 +16,7 @@ pub struct DeleteCertificateRequest {
 }
 
 #[derive(Deserialize, Serialize, Debug)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct CertificateResponse {
     pub id: String,
@@ -24,6 +26,7 @@ pub struct CertificateResponse {
 }
 
 #[derive(Deserialize, Serialize, Debug)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct CertificateListResponse {
     pub certificates: Vec<CertificateResponse>,

common/src/models/certificate.rs

@@ -8,6 +8,7 @@ use strum::{Display, EnumString};
 use crossterm::style::Stylize;
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Display, Serialize, EnumString)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
 #[strum(ascii_case_insensitive)]
@@ -65,12 +66,14 @@ impl DeploymentState {
 }
 
 #[derive(Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct DeploymentListResponse {
     pub deployments: Vec<DeploymentResponse>,
 }
 
 #[derive(Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct DeploymentResponse {
     pub id: String,
@@ -105,13 +108,15 @@ impl DeploymentResponse {
 }
 
 #[derive(Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct UploadArchiveResponse {
     /// The S3 object version ID of the uploaded object
     pub archive_version_id: String,
 }
 
 #[derive(Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(tag = "type", content = "content")]
 #[typeshare::typeshare]
 pub enum DeploymentRequest {
@@ -123,6 +128,7 @@ pub enum DeploymentRequest {
 }
 
 #[derive(Default, Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct DeploymentRequestBuildArchive {
     /// The S3 object version ID of the archive to use
@@ -135,6 +141,7 @@ pub struct DeploymentRequestBuildArchive {
 }
 
 #[derive(Deserialize, Serialize, Default)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(tag = "type", content = "content")]
 #[typeshare::typeshare]
 pub enum BuildArgs {
@@ -144,6 +151,7 @@ pub enum BuildArgs {
 }
 
 #[derive(Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct BuildArgsRust {
     /// Version of shuttle-runtime used by this crate
@@ -183,6 +191,7 @@ impl Default for BuildArgsRust {
 pub const GIT_STRINGS_MAX_LENGTH: usize = 80;
 
 #[derive(Default, Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct BuildMeta {
     pub git_commit_id: Option<String>,
@@ -209,6 +218,7 @@ impl std::fmt::Display for BuildMeta {
 }
 
 #[derive(Default, Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct DeploymentRequestImage {
     pub image: String,

common/src/models/deployment.rs

@@ -10,12 +10,14 @@ use std::fmt::Write;
 use super::deployment::DeploymentState;
 
 #[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct ProjectCreateRequest {
     pub name: String,
 }
 
 #[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct ProjectResponse {
     pub id: String,
@@ -64,13 +66,15 @@ impl ProjectResponse {
 }
 
 #[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct ProjectListResponse {
     pub projects: Vec<ProjectResponse>,
 }
 
 /// Set wanted field(s) to Some to update those parts of the project
 #[derive(Debug, Default, Deserialize, Serialize, Clone, PartialEq)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct ProjectUpdateRequest {
     /// Change display name
@@ -88,6 +92,7 @@ pub struct ProjectUpdateRequest {
 #[derive(
     Debug, Default, Clone, Copy, PartialEq, Eq, Display, Serialize, Deserialize, EnumString,
 )]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
 #[typeshare::typeshare]

common/src/models/project.rs

@@ -8,6 +8,7 @@ use serde::{Deserialize, Serialize};
 use strum::{EnumString, IntoStaticStr};
 
 #[derive(Debug, Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct UserResponse {
     pub id: String,
@@ -73,6 +74,7 @@ impl UserResponse {
 )]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub enum AccountTier {
     #[default]
@@ -89,6 +91,7 @@ pub enum AccountTier {
 }
 
 #[derive(Debug, Deserialize, Serialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct Subscription {
     pub id: String,
@@ -99,6 +102,7 @@ pub struct Subscription {
 }
 
 #[derive(Debug, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[typeshare::typeshare]
 pub struct SubscriptionRequest {
     pub id: String,
@@ -120,6 +124,7 @@ pub struct SubscriptionRequest {
     strum::Display,
     IntoStaticStr,
 )]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
 #[typeshare::typeshare]

common/src/models/user.rs

@@ -15,6 +15,7 @@ use zeroize::Zeroize;
 /// To make sure nothing leaks after the [`Secret`] has been dropped, a custom [`Drop`]
 /// implementation will zero-out the underlying memory.
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema), schema(value_type = String, format = "password"))]
 pub struct Secret<T: Zeroize>(T);
 
 impl<T: Zeroize> Debug for Secret<T> {