This projects serves to enable automatic rendering of `openapi.json` files, and provides
facilities to also serve the documentation alongside your api.
# Usage
First, add the following lines to your `Cargo.toml`
```toml
[dependencies]
rocket = { version = "0.5.0-rc.2", default-features = false, features = ["json"] }
schemars = "0.8.10"
okapi = { version = "0.7.0-rc.1" }
rocket_okapi = { version = "0.8.0-rc.2", features = ["swagger"] }
```
To add documentation to a set of endpoints, a couple of steps are required. The request and
response types of the endpoint must implement `JsonSchema`. Secondly, the function must be
marked with `#[openapi]`. After that, you can simply replace `routes!` with
`openapi_get_routes!`. This will append an additional route to the resulting `Vec`,
which contains the `openapi.json` file that is required by swagger. Now that we have the json
file that we need, we can serve the swagger web interface at another endpoint, and we should be
able to load the example in the browser!
### Example
```rust, no_run
use rocket::get;
use rocket::serde::json::Json;
use rocket_okapi::{openapi, openapi_get_routes, JsonSchema};
use rocket_okapi::swagger_ui::{make_swagger_ui, SwaggerUIConfig};
#[derive(serde::Serialize, JsonSchema)]
struct Response {
reply: String,
}
#[openapi]
#[get("/")]
fn my_controller() -> Json {
Json(Response {
reply: "show me the docs!".to_string(),
})
}
fn get_docs() -> SwaggerUIConfig {
use rocket_okapi::settings::UrlObject;
SwaggerUIConfig {
url: "/my_resource/openapi.json".to_string(),
..Default::default()
}
}
fn main() {
rocket::build()
.mount("/my_resource", openapi_get_routes![my_controller])
.mount("/swagger", make_swagger_ui(&get_docs()))
.launch();
}
```
This crate exposes a few macros that can be used to generate and serve routes and OpenApi objects.
- `mount_endpoints_and_merged_docs!{...}`: Mount endpoints and mount merged OpenAPI documentation.
- `openapi_get_routes![...]`: To generate and add the `openapi.json` route.
- `openapi_get_routes_spec![...]`: To generate and return a list of routes and the openapi spec.
- `openapi_get_spec![...]`: To generate and return the openapi spec.
The last 3 macros have very similar behavior, but differ in what they return.
Here is a list of the marcos and what they return:
- `openapi_get_routes![...]`: `Vec` (adds route for `openapi.json`)
- `openapi_get_routes_spec![...]`: `(Vec, okapi::openapi3::OpenApi)`
- `openapi_get_spec![...]`: `okapi::openapi3::OpenApi`
## FAQ
- **Q: My (diesel) database does not implement `OpenApiFromRequest`.**
A: This is because the parameter does not show up in the path, query or body.
So this is considered a [Request Guard](https://rocket.rs/v0.5-rc/guide/requests/#request-guards).
There is a [derive macro](https://github.com/GREsau/okapi/blob/master/examples/secure_request_guard/src/no_auth.rs)
for this, but this does not work in combination with the `#[database("...")]` marco.
You can solve this my implementing it manually, like this:
```rust, no_run
use rocket_okapi::request::{OpenApiFromRequest, RequestHeaderInput};
use rocket_okapi::gen::OpenApiGenerator;
use rocket_sync_db_pools::{diesel, database};
#[database("sqlite_logs")]
pub struct MyDB(diesel::SqliteConnection);
impl<'r> OpenApiFromRequest<'r> for MyDB {
fn from_request_input(
_gen: &mut OpenApiGenerator,
_name: String,
_required: bool,
) -> rocket_okapi::Result {
Ok(RequestHeaderInput::None)
}
}
```
- **Q: ... does not implement `JsonSchema`?**
A: The [`JsonSchema`](https://docs.rs/schemars/latest/schemars/trait.JsonSchema.html) implementation
is handled by [`Schemars`][Schemars], make sure you enabled the right
[feature flags](https://github.com/GREsau/schemars#optional-dependencies) for it.
If it is still not implemented open an issue in the `Schemars` repo.
- **Q: Can I add custom data to my OpenAPI spec?**
A: Yes, see the [Custom Schema](examples/custom_schema) example. Okapi also has build in functions
if you want to merge the [`OpenAPI`](https://docs.rs/okapi/latest/okapi/openapi3/struct.OpenApi.html)
objects manually.
- More FAQ questions and answers in [README.md](https://github.com/GREsau/okapi#readme).
