OpenAPI documentation for Axum using doc comments and macros.
Built on aide, Rovo provides a declarative approach to API documentation through special annotations in doc comments.
- Drop-in replacement for
axum::Router - Doc-comment driven documentation
- Compile-time validation of annotations
- Method chaining support (
.post(),.patch(),.delete()) - Built-in Swagger/Redoc/Scalar UI integration
- Type-safe response definitions
- Minimal runtime overhead
- Editor Integration:
- VSCode - See VSCODE.md for Visual Studio Code extension with auto-installation, completions, and syntax highlighting
- Neovim LSP - See NEOVIM.md for editor support with completions, hover docs, and more
- JetBrains IDEs - See JETBRAINS.md for RustRover, IntelliJ IDEA, and CLion support
use rovo::{rovo, Router, routing::get, schemars::JsonSchema};
use rovo::aide::{axum::IntoApiResponse, openapi::OpenApi};
use axum::{extract::State, response::Json};
use serde::Serialize;
#[derive(Clone)]
struct AppState {}
#[derive(Serialize, JsonSchema)]
struct User {
id: u64,
name: String,
}
/// Get user information.
///
/// Returns the current user's profile information.
///
/// @tag users
/// @response 200 Json<User> User profile retrieved successfully.
#[rovo]
async fn get_user(State(_state): State<AppState>) -> impl IntoApiResponse {
Json(User {
id: 1,
name: "Alice".to_string(),
})
}
#[tokio::main]
async fn main() {
let state = AppState {};
let mut api = OpenApi::default();
api.info.title = "My API".to_string();
let app = Router::new()
.route("/user", get(get_user))
.with_oas(api)
.with_swagger("/")
.with_state(state);
let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
.await
.unwrap();
axum::serve(listener, app).await.unwrap();
}[dependencies]
rovo = { version = "0.1.8", features = ["swagger"] }
axum = "0.8"
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }Note: Rovo re-exports
aideandschemars, so you don't need to add them as separate dependencies. Access them viarovo::aideandrovo::schemars.
For detailed API documentation, see docs.rs/rovo.
Choose one or more documentation UIs (none enabled by default):
swagger- Swagger UIredoc- Redoc UIscalar- Scalar UI
Document response status codes:
/// @response 200 Json<User> User found successfully
/// @response 404 () User not found
/// @response 500 Json<ErrorResponse> Internal server error
Provide example responses:
/// @response 200 Json<User> User information
/// @example 200 User { id: 1, name: "Alice".into(), email: "alice@example.com".into() }
Group operations by tags (can be used multiple times):
/// @tag users
/// @tag authentication
Specify security requirements (can be used multiple times):
/// @security bearer_auth
Security schemes must be defined in your OpenAPI spec. See Tips for details.
Set custom operation ID (defaults to function name):
/// @id getUserById
@hidden
Hide an operation from documentation:
/// @hidden
Mark endpoints as deprecated using Rust's built-in attribute:
#[deprecated]
#[rovo]
async fn old_handler() -> impl IntoApiResponse {
// ...
}Stop processing annotations after this point:
/// Get user information.
///
/// @tag users
/// @response 200 Json<User> User found successfully
/// @rovo-ignore
/// Additional documentation here won't be processed.
/// You can write @anything without causing errors.
#[rovo]
async fn handler() -> impl IntoApiResponse {
// ...
}use rovo::Router;
let app = Router::new()
.route("/path", get(handler))
.with_state(state);use rovo::routing::{get, post, patch, delete};
Router::new()
.route("/items", get(list_items).post(create_item))
.route("/items/{id}", get(get_item).patch(update_item).delete(delete_item))Router::new()
.nest(
"/api",
Router::new()
.route("/users", get(list_users))
.route("/posts", get(list_posts))
)Router::new()
.route("/users", get(list_users))
.with_oas(api)
.with_swagger("/swagger")
.with_redoc("/redoc")
.with_scalar("/scalar")
.with_state(state)Use custom OAS route:
Router::new()
.route("/users", get(list_users))
.with_oas_route(api, "/openapi")
.with_swagger("/")
.with_state(state)Rovo automatically serves your OpenAPI specification in multiple formats:
- JSON -
/api.json(default) - YAML -
/api.yamlor/api.yml
All formats are automatically available when you use .with_oas() or .with_oas_route().
See examples/todo_api.rs for a complete CRUD API.
Run with:
cargo run -F swagger --example todo_apiReplace imports and add documentation:
// Before
use axum::{Router, response::IntoResponse, routing::get};
async fn handler() -> impl IntoResponse {
Json(data)
}
// After
use rovo::{Router, routing::get, schemars::JsonSchema};
use rovo::aide::axum::IntoApiResponse;
/// Handler description
///
/// @tag category
/// @response 200 Json<Data> Success
#[rovo]
async fn handler() -> impl IntoApiResponse {
Json(data)
}Add OpenAPI setup in main():
use rovo::aide::openapi::OpenApi;
let mut api = OpenApi::default();
api.info.title = "My API".to_string();
let app = Router::new()
.route("/path", get(handler))
.with_oas(api)
.with_swagger("/")
.with_state(state);Use structs with JsonSchema:
use rovo::schemars::JsonSchema;
use serde::Deserialize;
use uuid::Uuid;
#[derive(Deserialize, JsonSchema)]
struct UserId {
id: Uuid,
}
#[rovo]
async fn get_user(Path(UserId { id }): Path<UserId>) -> impl IntoApiResponse {
// ...
}Define in OpenAPI object:
use rovo::aide::openapi::{SecurityScheme, SecuritySchemeData};
api.components.get_or_insert_default()
.security_schemes
.insert(
"bearer_auth".to_string(),
SecurityScheme {
data: SecuritySchemeData::Http {
scheme: "bearer".to_string(),
bearer_format: Some("JWT".to_string()),
},
..Default::default()
},
);Reference in handlers:
/// @security bearer_auth
#[rovo]
async fn protected_handler() -> impl IntoApiResponse {
// ...
}Add the #[rovo] macro:
#[rovo]
async fn handler() -> impl IntoApiResponse {
// ...
}Add explicit type annotation:
let router: Router<()> = Router::<AppState>::new()
.route("/path", get(handler))
.with_state(state);| Feature | aide | rovo |
|---|---|---|
| Documentation | Separate _docs function |
Doc comments |
| Routing | api_route() |
Native axum syntax |
| Method chaining | Custom | Standard axum |
| Lines per endpoint | ~15-20 | ~5-10 |
This project uses just for common development tasks.
# List all available commands
just
# Run all checks (format, clippy, tests)
just check
# Fix formatting and clippy issues
just fix
# Run tests
just test
# Check for outdated dependencies
just outdated
# Check for unused dependencies
just unused-deps
# Check for security vulnerabilities
just auditUses prek for git hooks:
prek install
prek run # Run manuallyjust test- Run all testsjust lint- Run clippy lintsjust fmt- Format codejust check- Run all checks (fmt, clippy, test)just fix- Run all checks and fixesjust build- Build the projectjust example- Run the todo_api examplejust outdated- Check for outdated dependenciesjust unused-deps- Check for unused dependenciesjust audit- Check for security vulnerabilitiesjust docs- Build and open documentationjust pre-release- Run all pre-release checks
See just --list for all available commands.
Contributions are welcome. Please submit a Pull Request.
MIT