BLOG-103 feat: add API documentation with Utoipa and configure routes

backend/.sqlx/query-9d1ffa7a71c8830d75eeeb26800ee7a7d8ede2410b423985caffd86361ad9263.json

@@ -0,0 +1,46 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n            SELECT id, issuer, source_id, displayed_name, email\n            FROM \"user\"\n            WHERE id = $1\n            ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": "Int4"
+      },
+      {
+        "ordinal": 1,
+        "name": "issuer",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 2,
+        "name": "source_id",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 3,
+        "name": "displayed_name",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 4,
+        "name": "email",
+        "type_info": "Varchar"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Int4"
+      ]
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "9d1ffa7a71c8830d75eeeb26800ee7a7d8ede2410b423985caffd86361ad9263"
+}

backend/Cargo.lock

@@ -2234,6 +2234,7 @@ dependencies = [
  "log",
  "serde",
  "sqlx",
+ "utoipa",
 ]
 
 [[package]]
@@ -2819,6 +2820,8 @@ dependencies = [
  "percent-encoding",
  "post",
  "sqlx",
+ "utoipa",
+ "utoipa-redoc",
 ]
 
 [[package]]
@@ -3509,6 +3512,42 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
+[[package]]
+name = "utoipa"
+version = "5.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2fcc29c80c21c31608227e0912b2d7fddba57ad76b606890627ba8ee7964e993"
+dependencies = [
+ "indexmap 2.9.0",
+ "serde",
+ "serde_json",
+ "utoipa-gen",
+]
+
+[[package]]
+name = "utoipa-gen"
+version = "5.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d79d08d92ab8af4c5e8a6da20c47ae3f61a0f1dabc1997cdf2d082b757ca08b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "regex",
+ "syn",
+]
+
+[[package]]
+name = "utoipa-redoc"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6427547f6db7ec006cbbef95f7565952a16f362e298b416d2d497d9706fef72d"
+dependencies = [
+ "actix-web",
+ "serde",
+ "serde_json",
+ "utoipa",
+]
+
 [[package]]
 name = "vcpkg"
 version = "0.2.15"

backend/Cargo.toml

@@ -30,6 +30,8 @@ sqlx = { version = "0.8.5", features = [
     "runtime-tokio-rustls",
 ] }
 tokio = { version = "1.45.0", features = ["full"] }
+utoipa = { version = "5.4.0", features = ["actix_extras"] }
+utoipa-redoc = { version = "6.0.0", features = ["actix-web"] }
 
 server.path = "server"
 auth.path = "feature/auth"

backend/server/Cargo.toml

@@ -12,6 +12,8 @@ hex.workspace = true
 openidconnect.workspace = true
 percent-encoding.workspace = true
 sqlx.workspace = true
+utoipa.workspace = true
+utoipa-redoc.workspace = true
 
 auth.workspace = true
 image.workspace = true

backend/server/src/apidoc.rs

@@ -0,0 +1,14 @@
+use actix_web::web;
+use utoipa::OpenApi;
+use utoipa_redoc::{Redoc, Servable};
+
+#[derive(OpenApi)]
+#[openapi(info(
+    title = "SquidSpirit API",
+    version = env!("CARGO_PKG_VERSION")
+))]
+pub struct ApiDoc;
+
+pub fn configure_api_doc_routes(cfg: &mut web::ServiceConfig) {
+    cfg.service(Redoc::with_url("/redoc", ApiDoc::openapi()));
+}

backend/server/src/lib.rs

@@ -1,2 +1,3 @@
+pub mod apidoc;
 pub mod configuration;
 pub mod container;

backend/server/src/main.rs

@@ -11,7 +11,7 @@ use auth::framework::web::auth_web_routes::configure_auth_routes;
 use image::framework::web::image_web_routes::configure_image_routes;
 use openidconnect::reqwest;
 use post::framework::web::post_web_routes::configure_post_routes;
-use server::{configuration::Configuration, container::Container};
+use server::{apidoc::configure_api_doc_routes, configuration::Configuration, container::Container};
 use sqlx::{Pool, Postgres};
 
 #[actix_web::main]
@@ -68,6 +68,7 @@ fn create_app(
         .app_data(web::Data::from(container.auth_controller))
         .app_data(web::Data::from(container.image_controller))
         .app_data(web::Data::from(container.post_controller))
+        .configure(configure_api_doc_routes)
         .configure(configure_auth_routes)
         .configure(configure_image_routes)
         .configure(configure_post_routes)