deployer & gateway: added OpenAPI docs (#794)

* deployer: added OpenAPI docs

* gateway: added OpenApi docs

* deployer & gateway: fixes to the openapi docs

* gateway(openapi): fixed responses' descriptions

Cargo.toml

@@ -93,4 +93,6 @@ tracing-subscriber = { version = "0.3.16", default-features = false, features =
   "std",
 ] }
 ttl_cache = "0.5.1"
+utoipa = { version = "3.2.1", features = [ "uuid", "chrono" ] }
+utoipa-swagger-ui = { version = "3.1.3", features = ["axum"] }
 uuid = "1.2.2"

common/Cargo.toml

@@ -40,6 +40,7 @@ tracing = { workspace = true, features = ["std"] }
 tracing-opentelemetry = { workspace = true, optional = true }
 tracing-subscriber = { workspace = true, optional = true }
 ttl_cache = { workspace = true, optional = true }
+utoipa = { workspace = true }
 uuid = { workspace = true, features = ["v4", "serde"], optional = true }
 
 [features]

common/src/database.rs

@@ -2,15 +2,17 @@ use std::fmt::Display;
 
 use serde::{Deserialize, Serialize};
 use strum::Display;
+use utoipa::ToSchema;
 
-#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq, ToSchema)]
 #[serde(rename_all = "lowercase")]
+#[schema(as = shuttle_common::database::Type)]
 pub enum Type {
     AwsRds(AwsRdsEngine),
     Shared(SharedEngine),
 }
 
-#[derive(Clone, Debug, Deserialize, Display, Serialize, Eq, PartialEq)]
+#[derive(Clone, Debug, Deserialize, Display, Serialize, Eq, PartialEq, ToSchema)]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
 pub enum AwsRdsEngine {
@@ -19,7 +21,7 @@ pub enum AwsRdsEngine {
     MariaDB,
 }
 
-#[derive(Clone, Debug, Deserialize, Display, Serialize, Eq, PartialEq)]
+#[derive(Clone, Debug, Deserialize, Display, Serialize, Eq, PartialEq, ToSchema)]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
 pub enum SharedEngine {

common/src/deployment.rs

@@ -1,9 +1,11 @@
 use serde::{Deserialize, Serialize};
 use strum::Display;
+use utoipa::ToSchema;
 
-#[derive(Clone, Debug, Deserialize, Display, Serialize)]
+#[derive(Clone, Debug, Deserialize, Display, Serialize, ToSchema)]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
+#[schema(as = shuttle_common::deployment::State)]
 pub enum State {
     Queued,
     Building,

common/src/log.rs

@@ -5,17 +5,23 @@ use chrono::{DateTime, Utc};
 #[cfg(feature = "display")]
 use crossterm::style::{StyledContent, Stylize};
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use uuid::Uuid;
 
 use crate::deployment::State;
 
 pub const STATE_MESSAGE: &str = "NEW STATE";
 
-#[derive(Clone, Debug, Deserialize, Serialize)]
+#[derive(Clone, Debug, Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::log::Item)]
 pub struct Item {
+    #[schema(value_type = KnownFormat::Uuid)]
     pub id: Uuid,
+    #[schema(value_type = KnownFormat::DateTime)]
     pub timestamp: DateTime<Utc>,
+    #[schema(value_type = shuttle_common::deployment::State)]
     pub state: State,
+    #[schema(value_type = shuttle_common::log::Level)]
     pub level: Level,
     pub file: Option<String>,
     pub line: Option<u32>,
@@ -77,8 +83,9 @@ impl std::fmt::Display for Item {
     }
 }
 
-#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq, ToSchema)]
 #[serde(rename_all = "lowercase")]
+#[schema(as = shuttle_common::log::Level)]
 pub enum Level {
     Trace,
     Debug,

common/src/models/deployment.rs

@@ -7,15 +7,21 @@ use comfy_table::{
 };
 use crossterm::style::Stylize;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use uuid::Uuid;
 
 use crate::deployment::State;
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::deployment::Response)]
 pub struct Response {
+    #[schema(value_type = KnownFormat::Uuid)]
     pub id: Uuid,
+    #[schema(value_type = KnownFormat::Uuid)]
     pub service_id: Uuid,
+    #[schema(value_type = shuttle_common::deployment::State)]
     pub state: State,
+    #[schema(value_type = KnownFormat::DateTime)]
     pub last_update: DateTime<Utc>,
 }
 

common/src/models/project.rs

@@ -6,18 +6,22 @@ use crossterm::style::Stylize;
 use serde::{Deserialize, Serialize};
 use std::fmt::{Display, Formatter};
 use strum::EnumString;
+use utoipa::ToSchema;
 
 // Timeframe before a project is considered idle
 pub const IDLE_MINUTES: u64 = 30;
 
-#[derive(Deserialize, Serialize, Clone)]
+#[derive(Deserialize, Serialize, Clone, ToSchema)]
+#[schema(as = shuttle_common::models::project::Response)]
 pub struct Response {
     pub name: String,
+    #[schema(value_type = shuttle_common::models::project::State)]
     pub state: State,
 }
 
-#[derive(Clone, Debug, Deserialize, Serialize, EnumString)]
+#[derive(Clone, Debug, Deserialize, Serialize, EnumString, ToSchema)]
 #[serde(rename_all = "lowercase")]
+#[schema(as = shuttle_common::models::project::State)]
 pub enum State {
     Creating { recreate_count: usize },
     Attaching { recreate_count: usize },
@@ -164,7 +168,8 @@ pub struct Config {
     pub idle_minutes: u64,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::project::AdminResponse)]
 pub struct AdminResponse {
     pub project_name: String,
     pub account_name: String,

common/src/models/secret.rs

@@ -5,10 +5,13 @@ use comfy_table::{
 };
 use crossterm::style::Stylize;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::secret::Response)]
 pub struct Response {
     pub key: String,
+    #[schema(value_type = KnownFormat::DateTime)]
     pub last_update: DateTime<Utc>,
 }
 

common/src/models/service.rs

@@ -1,19 +1,24 @@
-use crate::models::deployment;
-
 use crossterm::style::Stylize;
 use serde::{Deserialize, Serialize};
 use std::fmt::Display;
+use utoipa::ToSchema;
 use uuid::Uuid;
 
-#[derive(Deserialize, Serialize)]
+use crate::models::deployment;
+
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::service::Response)]
 pub struct Response {
+    #[schema(value_type = KnownFormat::Uuid)]
     pub id: Uuid,
     pub name: String,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::service::Summary)]
 pub struct Summary {
     pub name: String,
+    #[schema(value_type = shuttle_common::models::deployment::Response)]
     pub deployment: Option<deployment::Response>,
     pub uri: String,
 }

common/src/models/stats.rs

@@ -1,12 +1,15 @@
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
 use uuid::Uuid;
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::stats::LoadRequest)]
 pub struct LoadRequest {
     pub id: Uuid,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::models::stats::LoadResponse)]
 pub struct LoadResponse {
     pub builds_count: usize,
     pub has_capacity: bool,

common/src/resource.rs

@@ -2,25 +2,32 @@ use std::fmt::Display;
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
+use utoipa::ToSchema;
 
 use crate::database;
 
 /// Common type to hold all the information we need for a generic resource
-#[derive(Clone, Deserialize, Serialize)]
+#[derive(Clone, Deserialize, Serialize, ToSchema)]
+#[schema(as = shuttle_common::resource::Response)]
 pub struct Response {
     /// The type of this resource.
+    #[schema(value_type = shuttle_common::resource::Type)]
     pub r#type: Type,
 
     /// The config used when creating this resource. Use the [Self::r#type] to know how to parse this data.
+    #[schema(value_type = Object)]
     pub config: Value,
 
     /// The data associated with this resource. Use the [Self::r#type] to know how to parse this data.
+    #[schema(value_type = Object)]
     pub data: Value,
 }
 
-#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
+#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq, ToSchema)]
 #[serde(rename_all = "lowercase")]
+#[schema(as = shuttle_common::resource::Type)]
 pub enum Type {
+    #[schema(value_type = shuttle_common::database::Type)]
     Database(database::Type),
     Secrets,
     StaticFolder,

deployer/Cargo.toml

@@ -52,6 +52,8 @@ tracing-subscriber = { workspace = true, features = [
   "env-filter",
   "fmt",
 ] }
+utoipa = { workspace = true }
+utoipa-swagger-ui = { workspace = true }
 uuid = { workspace = true, features = ["v4"] }
 
 [dependencies.shuttle-common]