Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kurtbuilds/oasgen

Generates OpenAPI 3.0 spec based on Rust code. Works with axum, actix-web, or any/no framework.
https://github.com/kurtbuilds/oasgen

Last synced: 5 days ago
JSON representation

Generates OpenAPI 3.0 spec based on Rust code. Works with axum, actix-web, or any/no framework.

Awesome Lists containing this project

README 

        







    GitHub Contributors





    Stars





    Build Status





    Downloads





    Crates.io







# `oasgen` - OpenAPI Spec Generator



`oasgen` is a library to generate OpenAPI 3.0 specs from Rust server code (or any async functions). It supports:



- `actix` - actix-web

- `axum` - axum

- No framework - if you just want to register Rust functions to generate an OpenAPI spec file.



Contributions to support other web frameworks are welcome!



## Example



```rust

// Actix-web example

use actix_web::web::Json;

use actix_web::{App, HttpServer};

use oasgen::{oasgen, OaSchema, Server};

use serde::{Deserialize, Serialize};



#[derive(OaSchema, Deserialize)]

pub struct SendCode {

    pub mobile: String,

}



#[derive(Serialize, OaSchema, Debug)]

pub struct SendCodeResponse {

    pub found_account: bool,

}



#[oasgen]

async fn send_code(_body: Json) -> Json {

    Json(SendCodeResponse {

        found_account: false,

    })

}



#[tokio::main]

async fn main() {

    let server = Server::actix().post("/send-code", send_code).freeze();



    HttpServer::new(move || App::new().service(server.clone().into_service()))

        .bind(("127.0.0.1", 5000))

        .unwrap()

        .run()

        .await

        .unwrap()

}

```



```rust

// axum example

use oasgen::{OaSchema, Server, oasgen};

use axum::{Json, routing};

use serde::{Deserialize, Serialize};



#[derive(OaSchema, Deserialize)]

pub struct SendCode {

    pub mobile: String,

}



#[derive(Serialize, OaSchema, Debug)]

pub struct SendCodeResponse {

    pub found_account: bool,

}



#[oasgen]

async fn send_code(_body: Json) -> Json {

    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();

}

```



To compile the axum example, use the following dependencies:



```toml

[dependencies]

axum = ".."

oasgen = { version = "..", features = ["axum"] }

serde = { version = "..", features = ["derive"] }

tokio = { version = "..", features = ["full"] }

```



# Installation



```toml

[dependencies]

# At minimum, you probably want a server feature installed (axum, actix) to support that framework

oasgen = { version = "..", features = []}

```



There are several features for activating other libraries:



- `actix` - actix-web

- `axum` - axum

- `swagger-ui` - swagger ui

- `uuid` - uuid

- `chrono` - chrono

- `time` - time

- `sqlx` - sqlx



# Customizing the generated spec



You can customize the generated spec in many ways.



## Direct access to the OpenAPI struct



You have direct access to the OpenAPI struct, so you can customize it however you want.



```rust

let mut server = Server::new();

server.openapi.info.title = "My API".to_string();

server.openapi.components.schemas.insert("MySchema".to_string(), Schema::new_object());

server

    .get("/my-route", my_handler)

    .freeze();



```



Note that you must make any changes before calling `.freeze()` (which moves the OpenAPI struct into an Arc to be shared between threads).



## Customizing a Schema



You can hand-write an implementation of OaSchema instead of using derive to customize any Schema. If you do this, call

`register_schema` after the struct definition to add it to the spec.



```rust

use oasgen::{OaSchema, Schema, register_schema};



pub struct User {

    pub id: i32,

    pub name: String,

}



impl OaSchema for User {

    fn schema() -> Schema {

        let mut schema = Schema::new_object();

        schema.properties_mut().insert("id", Schema::new_integer());

        schema.properties_mut().insert("name", Schema::new_string());

        schema

    }

}

register_schema!("User", &|| User::schema());

```



Technically speaking, you don't need to implement OaSchema at all.

You can pass any arbitrary closure that returns a `Schema` to the register_schema macro.



You can also customize an operation:



```rust

async fn my_server_handler() {

    // ...

}



// You must use the fully qualified path to the function.

// You can simplify this slightly by passing in `concat!(module_path!(), "::my_server_handler")`

register_operation!("my_server_crate::path::to::my_server_handler", &|| {

    let mut operation = Operation::default();

    operation.summary = Some("My summary".to_string());

    // ...

    operation

});

```



# Attributes



`oasgen` defines its own attributes, and also respects `serde` attributes. It also uses docstrings as descriptions.

You can see all attributes in `macro/src/attr.rs`. Look at those structs for relevant documentation, and see the examples below.



```rust



#[derive(OaSchema)]

pub struct User {

    pub id: i32,

    pub name: String,

    // Because oasgen respects serde attributes, this will not appear in the spec.

    #[serde(skip)]

    pub password_hash: String,

    // This will be in the response (because there's no serde(skip), but it will not show up in the OpenAPI spec.

    #[oasgen(skip)]

    pub internal_id: i32,

}



#[oasgen(

tags("auth", "users"),

summary = "This is a short summary"),

deprecated = true,

operation_id = "my_operation_id",

description = "This is a long description and will override the docstring of the function",

)]

async fn my_server_handler() {

    // ...

}

```



# 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:



```rust

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



> [!NOTE]  

> Requires the `swagger-ui` feature 



There are built-in functions to create routes that display the raw spec, or display a Swagger UI 

page for the spec.



```rust

let mut server = oasgen::Server::axum()

    .post("/auth/register_password", auth::register_password) // example route

    .route_yaml_spec("/openapi.yaml") // the spec will be available at /openapi.yaml

    .route_json_spec("/openapi.json") // the spec will be available at /openapi.json

    .swagger_ui("/openapi/"); // the swagger UI will be available at /openapi/.

                              // NOTE: The trailing slash is required, as is calling either `route_yaml_spec()` or `route_json_spec()` before `swagger_ui()`.

```



If you need to customize these routes, you have directly use a clone of the OpenAPI struct. It's in an Arc, so it's cheap to clone.



```rust

let mut server = oasgen::Server::axum()

    .post("/auth/register_password", auth::register_password) // example route

    .freeze();

let spec = server.openapi.clone();

let router = axum::Router::new()

    .merge(server.into_router())

    .route("/alt/route/to/openapi.yaml", get(|| {

        let spec = spec.clone();

        async { 

            serde_yaml::to_string(spec).unwrap()

        }

    }))

;