1 unstable release
0.7.1 | Jul 7, 2021 |
---|
#70 in #swagger
Used in rocket_okapi_fork
25KB
587 lines
okapi ( Dont USE this version, the original has been updated )
OpenAPI (AKA Swagger) document generation for Rust projects forked version to enable some new features
only change your usage in Cargo toml to something like this by adding the "package" parameter:
okapi = { version = "0.x.x", features = ["derive_json_schema"], package = "okapi_fork" }
rocket_okapi = { version = "0.x.x", package = "rocket_okapi_fork" }
Work in progress!
Basic Usage
#[macro_use]
extern crate rocket;
#[macro_use]
extern crate rocket_okapi;
use rocket_contrib::json::Json;
use rocket_okapi::swagger_ui::make_swagger_ui;
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;
// Derive JsonSchema for and request/response models
#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
struct User {
user_id: u64,
username: String,
#[serde(default)]
email: Option<String>,
}
// Add #[openapi] attribute to your routes
#[openapi]
#[get("/user/<id>")]
fn get_user(id: u64) -> Option<Json<User>> {
Some(Json(User {
user_id: id,
username: "bob".to_owned(),
email: None,
}))
}
// You can tag your routes to group them together
#[openapi(tag = "Users")]
#[post("/user", data = "<user>")]
fn create_user(user: Json<User>) -> Json<User> {
user
}
// You can skip routes that you don't want to include in the openapi doc
#[openapi(skip)]
#[get("/hidden")]
fn hidden() -> Json<&'static str> {
Json("Hidden from swagger!")
}
pub fn make_rocket() -> rocket::Rocket {
rocket::build()
// routes_with_openapi![...] will host the openapi document at openapi.json
.mount(
"/",
routes_with_openapi![get_user, hidden],
)
// You can optionally host swagger-ui too
.mount(
"/swagger-ui/",
make_swagger_ui(&SwaggerUIConfig {
url: "../openapi.json".to_owned(),
..Default::default()
}),
)
}
TODO
- Tests
- Documentation
- Benchmark/optimise memory usage and allocations
- Note to self: https://crates.io/crates/graphannis-malloc_size_of looks useful
- Implement
OpenApiFrom___
/OpenApiResponder
for more rocket/rocket-contrib types - Allow customizing openapi generation settings, e.g.
- custom json schema generation settings
- change path the document is hosted at
Dependencies
~9–37MB
~553K SLoC