soai

Crates.iosoai
lib.rssoai
version0.1.0
sourcesrc
created_at2022-12-13 02:20:20.765064
updated_at2022-12-13 02:20:20.765064
descriptionOpenApi support for salvo.
homepagehttps://github.com/salvo-rs/soai
repositoryhttps://github.com/salvo-rs/soai
max_upload_size
id735394
size19,978
Chrislearn Young (chrislearn)

documentation

https://docs.rs/soai/

README

soai OpenApi

Fast and Type-Safe OpenApi implementation for soai.

Crates.io version Download docs.rs docs Unsafe Rust forbidden rustc 1.56.1+

soai allows you to easily implement Apis that comply with the OpenApiv3 specification. It uses procedural macros to generate a lots of boilerplate code, so that you only need to focus on the more important business implementations.

Features

  • Type safety If your codes can be compiled, then it is fully compliant with the OpenApi v3 specification.
  • Rustfmt friendly Do not create any DSL that does not conform to Rust's syntax specifications.
  • IDE friendly Any code generated by the procedural macro will not be used directly.
  • Minimal overhead All generated code is necessary, and there is almost no overhead.

Crate features

To avoid compiling unused dependencies, soai gates certain features, some of which are disabled by default:

Feature Description
chrono Integrate with the chrono crate.
swagger-ui Add swagger UI support
rapidoc Add RapiDoc UI support
redoc Add Redoc UI support
email Support for email address string
hostname Support for hostname string
uuid Integrate with the uuid crate
url Integrate with the url crate
bson Integrate with the bson crate
rust_decimal Integrate with the rust_decimal crate
static-files Support for static file response

Safety

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% Safe Rust.

Example

use soai::{listener::TcpListener, Route};
use soai::{param::Query, payload::PlainText, OpenApi, OpenApiService};

struct Api;

#[OpenApi]
impl Api {
    #[oai(path = "/hello", method = "get")]
    async fn index(&self, name: Query<Option<String>>) -> PlainText<String> {
        match name.0 {
            Some(name) => PlainText(format!("hello, {}!", name)),
            None => PlainText("hello!".to_string()),
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    let api_service =
        OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000/api");
    let ui = api_service.swagger_ui();
    let app = Route::new().nest("/api", api_service).nest("/", ui);

    soai::Server::new(TcpListener::bind("127.0.0.1:3000"))
        .run(app)
        .await
}

This feature needs to be opted-in. It can be done by adding the feature in Cargo.toml file

[dependencies]
soai = "1.3.29"
soai = { version = "1.3.29", features = ["swagger-ui"]}
tokio = { version = "1", features = ["full"] }

Run example

Open http://localhost:3000/ in your browser, you will see the Swagger UI that contains these Api definitions.

> cargo run --example hello_world

> curl http://localhost:3000
hello!

> curl http://localhost:3000\?name\=chris
hello, chris!        

MSRV

The minimum supported Rust version for this crate is 1.56.1.

Contributing

:balloon: Thanks for your help improving the project! We are so happy to have you!

License

Licensed under either of

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in soai by you, shall be licensed as Apache, without any additional terms or conditions.

Commit count: 0

cargo fmt