salvo-oapi 0.92.0

OpenApi support for Salvo web framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

OpenAPI support for the Salvo web framework.

This crate provides automatic OpenAPI documentation generation using simple
procedural macros. Annotate your handlers and types, and get a complete OpenAPI
specification.

# Quick Start

1. Add the `oapi` feature to your Salvo dependency
2. Use `#[endpoint]` instead of `#[handler]` on your handlers
3. Derive `ToSchema` on your data types
4. Create an `OpenApi` instance and mount the Swagger UI

```ignore
use salvo::prelude::*;
use salvo::oapi::extract::*;

#[derive(ToSchema, serde::Deserialize)]
struct User {
    id: i64,
    name: String,
}

#[endpoint]
async fn get_user(id: PathParam<i64>) -> Json<User> {
    Json(User { id: *id, name: "Alice".into() })
}

#[tokio::main]
async fn main() {
    let router = Router::new()
        .push(Router::with_path("users/<id>").get(get_user));

    let doc = OpenApi::new("My API", "1.0.0").merge_router(&router);

    let router = router
        .push(doc.into_router("/api-doc/openapi.json"))
        .push(SwaggerUi::new("/api-doc/openapi.json").into_router("/swagger-ui"));

    let acceptor = TcpListener::new("127.0.0.1:8080").bind().await;
    Server::new(acceptor).serve(router).await;
}
```

# Key Traits

| Trait | Purpose | Derive Macro |
|-------|---------|--------------|
| [`ToSchema`] | Define JSON schema for types | `#[derive(ToSchema)]` |
| [`ToParameters`] | Define query/path parameters | `#[derive(ToParameters)]` |
| [`ToResponse`] | Define a single response type | `#[derive(ToResponse)]` |
| [`ToResponses`] | Define multiple response types | `#[derive(ToResponses)]` |

# Documentation UIs

Multiple OpenAPI documentation UIs are available:

| UI | Feature Flag | Description |
|----|--------------|-------------|
| Swagger UI | `swagger-ui` | Interactive API explorer |
| Scalar | `scalar` | Modern, beautiful API docs |
| RapiDoc | `rapidoc` | Customizable API documentation |
| ReDoc | `redoc` | Clean, responsive documentation |

# Crate Features

## Serialization

- **`yaml`** - Enable YAML serialization of OpenAPI objects

## Type Support

- **`chrono`** - Support for `chrono` date/time types (`DateTime`, `Date`, `NaiveDate`, `Duration`)
  - `DateTime` uses `format: date-time` per [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
  - `Date` and `NaiveDate` use `format: date`

- **`time`** - Support for `time` crate types (`OffsetDateTime`, `PrimitiveDateTime`, `Date`, `Duration`)

- **`decimal`** - Support for `rust_decimal::Decimal` as String (default)

- **`decimal-float`** - Support for `rust_decimal::Decimal` as Number (mutually exclusive with `decimal`)

- **`uuid`** - Support for `uuid::Uuid` with `format: uuid`

- **`ulid`** - Support for `ulid::Ulid` with `format: ulid`

- **`url`** - Support for `url::Url` with `format: uri`

- **`smallvec`** - Support for `SmallVec` (rendered as array)

- **`indexmap`** - Support for `IndexMap` (rendered as object)

# Examples

Browse the [examples directory](https://github.com/salvo-rs/salvo/tree/master/examples)
for comprehensive examples including:

- `oapi-hello` - Basic OpenAPI setup
- `oapi-todos` - CRUD API with documentation
- `oapi-upload` - File upload documentation

# Learn More

- [`derive@ToSchema`] - Schema derivation with all attributes
- [`derive@ToParameters`] - Parameter extraction documentation
- [`derive@ToResponse`] / [`derive@ToResponses`] - Response documentation
- [`endpoint`] - Endpoint macro documentation
- [Security documentation][security] - API authentication setup

[security]: openapi/security/index.html
[to_schema_derive]: derive.ToSchema.html