From 1d28ec616b71c7dfb3917a3ca61c0ef0faf04300 Mon Sep 17 00:00:00 2001 From: SquidSpirit Date: Sat, 2 Aug 2025 03:35:03 +0800 Subject: [PATCH] BLOG-103 feat: add API documentation with Utoipa and configure routes --- ...ee7a7d8ede2410b423985caffd86361ad9263.json | 46 +++++++++++++++++++ backend/Cargo.lock | 39 ++++++++++++++++ backend/Cargo.toml | 2 + backend/server/Cargo.toml | 2 + backend/server/src/apidoc.rs | 14 ++++++ backend/server/src/lib.rs | 1 + backend/server/src/main.rs | 3 +- 7 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 backend/.sqlx/query-9d1ffa7a71c8830d75eeeb26800ee7a7d8ede2410b423985caffd86361ad9263.json create mode 100644 backend/server/src/apidoc.rs diff --git a/backend/.sqlx/query-9d1ffa7a71c8830d75eeeb26800ee7a7d8ede2410b423985caffd86361ad9263.json b/backend/.sqlx/query-9d1ffa7a71c8830d75eeeb26800ee7a7d8ede2410b423985caffd86361ad9263.json new file mode 100644 index 0000000..e8eb2c6 --- /dev/null +++ b/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" +} diff --git a/backend/Cargo.lock b/backend/Cargo.lock index 7ffa59d..ad782b8 100644 --- a/backend/Cargo.lock +++ b/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" diff --git a/backend/Cargo.toml b/backend/Cargo.toml index 272ab65..91ce1e9 100644 --- a/backend/Cargo.toml +++ b/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" diff --git a/backend/server/Cargo.toml b/backend/server/Cargo.toml index 938f82e..8e5a7b1 100644 --- a/backend/server/Cargo.toml +++ b/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 diff --git a/backend/server/src/apidoc.rs b/backend/server/src/apidoc.rs new file mode 100644 index 0000000..e844567 --- /dev/null +++ b/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())); +} diff --git a/backend/server/src/lib.rs b/backend/server/src/lib.rs index 18fb4fc..9703715 100644 --- a/backend/server/src/lib.rs +++ b/backend/server/src/lib.rs @@ -1,2 +1,3 @@ +pub mod apidoc; pub mod configuration; pub mod container; diff --git a/backend/server/src/main.rs b/backend/server/src/main.rs index adc4724..1e36bf1 100644 --- a/backend/server/src/main.rs +++ b/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)