SquidSpirit
e255e076dc
All checks were successful
Frontend CI / build (push) Successful in 1m8s
### Description
This PR integrates the **`utoipa`** and **`utoipa-redoc`** crates to automatically generate OpenAPI-compliant API documentation for the backend project.
#### Overview
To improve development efficiency and API maintainability, this change introduces `utoipa` to automate the API documentation process. By adding specific attribute macros to the source code, we can generate detailed API specifications directly and serve them through an interactive UI provided by `utoipa-redoc`.
#### Key Changes
* **Dependencies Added**
* Added `utoipa`, `utoipa-gen`, and `utoipa-redoc` to `Cargo.toml`.
* `utoipa` is used to define OpenAPI objects.
* `utoipa-redoc` is used to serve the ReDoc documentation UI.
* **Code Refactoring**
* **HTTP handler logic** in each feature (`auth`, `image`, `post`) has been extracted from the `..._web_routes.rs` files into their own dedicated files (e.g., `get_post_by_id_handler.rs`). This makes the code structure cleaner and simplifies adding documentation attributes to each handler.
* Renamed the `PostController` method from `get_full_post` to `get_post_by_id` for a more RESTful-compliant naming convention.
* **API Doc Annotation**
* Added `#[derive(ToSchema)]` or `#[derive(IntoParams)]` to all DTOs (Data Transfer Objects) so they can be recognized by `utoipa` to generate the corresponding schemas.
* Added the `#[utoipa::path]` macro to all HTTP handler functions, describing the API's path, HTTP method, tags, summary, expected responses, and security settings.
* **Doc Aggregation & Serving**
* Added an `..._api_doc.rs` file in each feature module to aggregate all API paths within that module.
* Added a new `api_doc.rs` file in the `server` crate to merge the OpenAPI documents from all features, set global information (like title, version, and the OAuth2 security scheme), and serve the documentation page on the `/redoc` route using `Redoc::with_url`.
### Package Changes
```toml
utoipa = { version = "5.4.0", features = ["actix_extras"] }
utoipa-redoc = { version = "6.0.0", features = ["actix-web"] }
```
### Screenshots
### Reference
Resolves #103
### Checklist
- [x] A milestone is set
- [x] The related issuse has been linked to this branch
Reviewed-on: #106
Co-authored-by: SquidSpirit <squid@squidspirit.com>
Co-committed-by: SquidSpirit <squid@squidspirit.com>
40 lines
998 B
TOML
40 lines
998 B
TOML
[workspace]
|
|
members = ["server", "feature/auth", "feature/image", "feature/post"]
|
|
resolver = "2"
|
|
|
|
[workspace.package]
|
|
version = "0.2.0"
|
|
edition = "2024"
|
|
|
|
[workspace.dependencies]
|
|
actix-multipart = "0.7.2"
|
|
actix-session = { version = "0.10.1", features = ["redis-session"] }
|
|
actix-web = "4.10.2"
|
|
async-trait = "0.1.88"
|
|
chrono = "0.4.41"
|
|
dotenv = "0.15.0"
|
|
env_logger = "0.11.8"
|
|
futures = "0.3.31"
|
|
hex = "0.4.3"
|
|
log = "0.4.27"
|
|
openidconnect = { version = "4.0.1", features = [
|
|
"reqwest",
|
|
"reqwest-blocking",
|
|
] }
|
|
percent-encoding = "2.3.1"
|
|
serde = { version = "1.0.219", features = ["derive"] }
|
|
sqlx = { version = "0.8.5", features = [
|
|
"chrono",
|
|
"macros",
|
|
"postgres",
|
|
"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"
|
|
image.path = "feature/image"
|
|
post.path = "feature/post"
|