soai OpenApi
Fast and Type-Safe OpenApi implementation for soai.
***
`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.
* [Docs](https://docs.rs/soai)
* [Cargo package](https://crates.io/crates/soai)
## 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](https://crates.io/crates/chrono). |
| 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](https://crates.io/crates/uuid) |
| url | Integrate with the [`url` crate](https://crates.io/crates/url) |
| bson | Integrate with the [`bson` crate](https://crates.io/crates/bson) |
| rust_decimal | Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal) |
| static-files | Support for static file response |
## Safety
This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% Safe Rust.
## Example
```rust
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>) -> PlainText {
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
```toml filename=Cargo.toml
[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.
```shell
> 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
* Apache License, Version 2.0,([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### 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.
