26 releases (14 breaking)
new 0.15.0 | Dec 3, 2023 |
---|---|
0.14.0 | Oct 31, 2023 |
0.13.0 | Jul 29, 2023 |
0.7.2 | Mar 27, 2023 |
0.1.8 | Dec 27, 2022 |
#886 in Procedural macros
406 downloads per month
Used in oasgen
29KB
621 lines
NOTE: This is work in progress software. It works great, but many features aren't implemented.
oasgen
- OpenAPI Spec Generator
oasgen
is a library to generate OpenAPI 3.0 specs from Rust server code (or any async functions). We currently support:
actix
- actix-webaxum
- axum- No framework at all - if you just want to register Rust functions to generate an OpenAPI spec file.
Contributions to support other web frameworks are welcome!
Example
// Actix-web example
use oasgen::{OaSchema, Server, openapi};
use actix_web::web::Json;
use serde::{Deserialize, Serialize};
#[derive(OaSchema, Deserialize)]
pub struct SendCode {
pub mobile: String,
}
#[derive(Serialize, OaSchema, Debug)]
pub struct SendCodeResponse {
pub found_account: bool,
}
#[openapi]
async fn send_code(_body: Json<SendCode>) -> Json<SendCodeResponse> {
Json(SendCodeResponse { found_account: false })
}
#[tokio::main]
async fn main() {
let server = Server::new()
.post("/send-code", send_code)
.freeze();
HttpServer::new(move || {
App::new()
.service(server.clone().into_service())
})
.bind("0.0.0.0:5000")
.unwrap()
.run()
.await
.unwrap()
}
// axum example
use oasgen::{OaSchema, Server, openapi};
use axum::Json;
use serde::{Deserialize, Serialize};
#[derive(OaSchema, Deserialize)]
pub struct SendCode {
pub mobile: String,
}
#[derive(Serialize, OaSchema, Debug)]
pub struct SendCodeResponse {
pub found_account: bool,
}
#[openapi]
async fn send_code(_body: Json<SendCode>) -> Json<SendCodeResponse> {
Json(SendCodeResponse { found_account: false })
}
#[tokio::main]
async fn main() {
let server = Server::axum()
.post("/send-code", send_code)
.freeze();
let router = axum::Router::new()
.route("/healthcheck", routing::get(|| async { "OK" }))
.merge(server.into_router());
axum::Server::bind("0.0.0.0:5000".parse().unwrap())
.serve(router.into_make_service())
.await
.unwrap();
}
Installation
[dependencies]
# For actix-web support
oasgen = ".."
There are several features for activating other libraries:
actix
- actix-webaxum
- axumuuid
- uuidchrono
- chronotime
- timesqlx
- sqlx
Customizing the generated spec
You can customize the autogenerated OpenAPI schemas and operations by defining custom wrapper types which implement OaSchema
, and then have your handler functions use those wrapper types in argument or return position.
More documentation to follow on how to do this.
Debugging
Here are some issues you might encounter:
Manually customizing the spec
On a Server
, you have direct access to the openapi
field. You can modify it as you wish.
See Customizing the generated spec for instructions on how to customize the autogeneration process.
Write the spec to a file
You have direct access to the OpenAPI
struct. You can use serde
to write it to a file, stdout, and more.
We provide a helper function write_and_exit_if_env_var_set
that integrates well with a basic build process:
let server = Server::new()
// your routes
.write_and_exit_if_env_var_set("./openapi.yaml")
// .freeze() here, if you're mounting to a server.
If OASGEN_WRITE_SPEC=1
, it will write the spec to the path, then exit.
In your build process, build the executable, run it once with the env var set to output the spec, then run it again without the env var to start the server normally.
Route that displays the spec
It's easiest to use the built-in methods: Server::route_json_spec
and Server::route_yaml_spec
.
If you need to customize these routes, you have direct access to the OpenAPI object.
Dependencies
~2.6–3.5MB
~64K SLoC