You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<a href="https://github.com/ohkami-rs/ohkami/actions"><img alt="build check status of ohkami" src="https://github.com/ohkami-rs/ohkami/actions/workflows/CI.yml/badge.svg"/></a>
Ohkami supports *as consistent as possible* OpenAPI document generation, where most of the consistency between document and behavior is automatically assured by Ohkami's internal work.
160
+
161
+
Only you have to
162
+
163
+
- Derive `openapi::Schema` for all your schema structs
164
+
- Make your `Ohkami` call `.generate(openapi::OpenAPI { ... })`
165
+
166
+
to generate consistent OpenAPI document. You don't need to take care of writing accurate methods, paths, parameters, contents, ... for this OpenAPI feature; All they are done by Ohkami.
167
+
168
+
Of course, you can flexibly customize schemas ( by hand-implemetation of `Schema` ), descriptions or other parts ( by `#[operation]` attribute and `openapi_*` hooks ).
169
+
170
+
```rust,ignore
171
+
use ohkami::prelude::*;
172
+
use ohkami::format::JSON;
173
+
use ohkami::typed::status;
174
+
use ohkami::openapi;
175
+
176
+
// Derive `Schema` trait to generate
177
+
// the schema of this struct in OpenAPI document.
178
+
#[derive(Deserialize, openapi::Schema)]
179
+
struct CreateUser<'req> {
180
+
name: &'req str,
181
+
}
182
+
183
+
#[derive(Serialize, openapi::Schema)]
184
+
// `#[openapi(component)]` to define it as component
185
+
// in OpenAPI document.
186
+
#[openapi(component)]
187
+
struct User {
188
+
id: usize,
189
+
name: String,
190
+
}
191
+
192
+
async fn create_user(
193
+
JSON(CreateUser { name }): JSON<CreateUser<'_>>
194
+
) -> status::Created<JSON<User>> {
195
+
status::Created(JSON(User {
196
+
id: 42,
197
+
name: name.to_string()
198
+
}))
199
+
}
200
+
201
+
// (optionally) Set operationId, summary,
202
+
// or override descriptions by `operation` attribute.
203
+
#[openapi::operation({
204
+
summary: "...",
205
+
200: "List of all users",
206
+
})]
207
+
/// This doc comment is used for the
208
+
/// `description` field of OpenAPI document
209
+
async fn list_users() -> JSON<Vec<User>> {
210
+
JSON(vec![])
211
+
}
212
+
213
+
#[tokio::main]
214
+
async fn main() {
215
+
let o = Ohkami::new((
216
+
"/users"
217
+
.GET(list_users)
218
+
.POST(create_user),
219
+
));
220
+
221
+
// This make your Ohkami spit out `openapi.json`
222
+
// ( the file name is configurable by `.generate_to` ).
223
+
o.generate(openapi::OpenAPI {
224
+
title: "Users Server",
225
+
version: "0.1.0",
226
+
servers: vec![
227
+
openapi::Server::at("localhost:5000"),
228
+
]
229
+
});
230
+
231
+
o.howl("localhost:5000").await;
232
+
}
233
+
```
234
+
235
+
- Currently, only **JSON** is supported as the document format.
236
+
- When the binary size matters, you should prepare a feature flag activating `ohkami/openapi` in your package, and put all your codes around `openapi` behind that feature via `#[cfg(feature = ...)]` or `#[cfg_attr(feature = ...)]`.
237
+
- In `rt_worker`, `.generate` is not available because `Ohkami` can't have access to your local filesystem by `wasm32` binary on Minifalre. So ohkami provides [a CLI tool](./scripts/workers_openapi.js) to generate document from `#[ohkami::worker] Ohkami` with `openapi` feature.
238
+
239
+
### `"nightly"`：nightly-only functionalities
154
240
155
241
- try response
156
242
@@ -162,29 +248,40 @@ async fn main() {
162
248
163
249
Ohkami's request handling system is called "**fang**s", and middlewares are implemented on this.
0 commit comments