oasgen

To automate spec generation in a build process, use the write_and_exit_if_env_var_set(path) method.

If the environment variable OASGEN_WRITE_SPEC=1 is set, the library will write the spec to the provided path and then exit the process. This allows you to generate the file during a build step before running the actual server.

let server = Server::new()
    // your routes
    .write_and_exit_if_env_var_set("./openapi.yaml")
    // .freeze() here, if you're mounting to a server.

To use oasgen, add it to your Cargo.toml. You should enable features for the web framework you are using (e.g., axum or actix) to allow the generator to integrate with your server routes.

Available features:

• actix: support for actix-web
• axum: support for axum
• swagger-ui: support for Swagger UI routes
• uuid: support for UUID types
• chrono: support for Chrono types
• time: support for Time types
• sqlx: support for SQLx types

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

The OaParameter trait is automatically implemented for Result<T, E> where T implements OaParameter. This allows you to define parameter logic directly on your success types, and the implementation will propagate the schema and parameter definitions through the Result wrapper.

// If T implements OaParameter, Result<T, E> also implements it automatically
impl<T, E> OaParameter for Result<T, E>
where
    T: OaParameter,
{
    fn body_schema() -> Option<RefOr<Schema>> {
        T::body_schema()
    }
    // ...
}

To use oasgen with the Axum web framework, use the axum() method on the Server struct. This initializes a server instance configured with an Axum Router. You can then register HTTP routes which will simultaneously be added to your Axum router and your OpenAPI specification.

// Assuming Server and OpenAPI are in scope
let server = Server::axum()
    .get("/hello", hello_handler)
    .post("/data", post_handler);

let app = server.into_router();

To use oasgen with an Actix-web server, initialize a server using Server::actix(), register your routes using HTTP method helpers, and then convert the server into an Actix Scope using .into_service(). This Scope can be registered directly within your Actix App.

// Example of initializing and integrating with Actix
let server = Server::actix()
    .get("/hello", hello_handler)
    .post("/data", data_handler)
    .route_json_spec("/openapi.json")
    .freeze();

App::new()
    .service(server.into_service())

If #[derive(OaSchema)] is insufficient, you can manually implement the OaSchema trait for a type. Alternatively, you can use the register_schema! macro to pass a closure that returns a Schema object.

To ensure the schema is included in the generated spec, you must call register_schema! after the struct definition.

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

If you have the swagger-ui feature enabled, you can add built-in routes to your server to serve the spec or the Swagger UI.

Requirements for Swagger UI:

1. You must call route_yaml_spec() or route_json_spec() before calling swagger_ui().
2. The swagger_ui() path must have a trailing slash (e.g., "/openapi/").

Available methods:

• route_yaml_spec(path): Serves the YAML spec at the given path.
• route_json_spec(path): Serves the JSON spec at the given path.
• swagger_ui(path): Serves the Swagger UI at the given path.

let mut server = oasgen::Server::axum()
    .post("/auth/register_password", auth::register_password)
    .route_yaml_spec("/openapi.yaml")
    .route_json_spec("/openapi.json")
    .swagger_ui("/openapi/");

You can modify the underlying OpenAPI struct before calling .freeze(). This allows you to set the API title or manually insert schemas into the components section.

Important: All modifications must be made before calling .freeze(), as .freeze() moves the struct into an Arc for thread-safe sharing.

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

You can override operation details (like summary, description, etc.) using the register_operation! macro. This requires the fully qualified path to the handler function. You can use concat!(module_path!(), "::my_handler") to simplify the path string.

// You must use the fully qualified path to the function.
register_operation!("my_server_crate::path::to::my_server_handler", &|| {
    let mut operation = Operation::default();
    operation.summary = Some("My summary".to_string());
    // ...
    operation
});