squid/blog
squid/blog
1
2
Fork 0
Code Issues 10 Pull Requests Actions Projects 1 Releases 7 Wiki Activity

BLOG-103 Add API documentation with Utoipa #106

Merged
squid merged 4 commits from BLOG-103_backend_api_doc into main 2025-08-02 06:51:37 +08:00
Conversation 2 Commits 4 Files Changed 36 +612 -247
squid commented 2025-08-02 06:49:42 +08:00
Owner
Copy Link

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

utoipa = { version = "5.4.0", features = ["actix_extras"] }
utoipa-redoc = { version = "6.0.0", features = ["actix-web"] }

Screenshots

image.png

Reference

Resolves #103

Checklist

  • A milestone is set
  • The related issuse has been linked to this branch
### 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 ![image.png](/attachments/f5b4b268-f550-4d9e-9321-49a00f6b8e1a) ### Reference Resolves #103 ### Checklist - [x] A milestone is set - [x] The related issuse has been linked to this branch
image.png
1.1 MiB
squid added this to the 0.3 milestone 2025-08-02 06:49:42 +08:00
squid added 4 commits 2025-08-02 06:49:42 +08:00
BLOG-103 feat: add API documentation with Utoipa and configure routes
All checks were successful
Frontend CI / build (push) Successful in 1m10s
Details
1d28ec616b
BLOG-103 feat: add OIDC authentication handlers and integrate Utoipa for API documentation
All checks were successful
Frontend CI / build (push) Successful in 1m10s
Details
Auto Comment On PR / add_improve_comment (pull_request) Successful in 17s
Details
PR Title Check / pr-title-check (pull_request) Successful in 16s
Details
68100e9b54
bot commented 2025-08-02 06:49:48 +08:00
Collaborator
Copy Link

/improve

/improve
bot commented 2025-08-02 06:49:54 +08:00
Collaborator
Copy Link

PR Code Suggestions ✨

No code suggestions found for the PR.

## PR Code Suggestions ✨ No code suggestions found for the PR.
squid changed title from BLOG-103 feat: add API documentation with Utoipa and configure routes to BLOG-103 Add API documentation with Utoipa 2025-08-02 06:51:03 +08:00
squid merged commit e255e076dc into main 2025-08-02 06:51:37 +08:00
squid deleted branch BLOG-103_backend_api_doc 2025-08-02 06:51:37 +08:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something is not working
design
dev
automation
dev
backend
dev
frontend
dev
improvement
duplicate
This issue or pull request already exists
enhancement
New feature
help wanted
Need some help
invalid
Something is wrong
question
More information is needed
wontfix
This won't be fixed
No Label
Milestone
No items
No Milestone 0.3
Projects
Clear projects
No project
Assignees
Clear assignees
bot zoe squid
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: squid/blog#106
No description provided.
Delete Branch "BLOG-103_backend_api_doc"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?