README.md

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-web
• axum - 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-web
• axum - axum
• uuid - uuid
• chrono - chrono
• time - time
• sqlx - 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.