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

[dependencies]
rocket = { version = "0.5.0-rc.1", default-features = false, features = ["json"] }
schemars = "0.8"
okapi = { version = "0.6.0-alpha-1" }
revolt_rocket_okapi = { version = "0.8.0-alpha-1", 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<Route>, 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

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<Response> {
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<rocket::Route> (adds route for openapi.json)
openapi_get_routes_spec![...]: (Vec<rocket::Route>, okapi::openapi3::OpenApi)
openapi_get_spec![...]: okapi::openapi3::OpenApi

revolt_rocket_okapi 0.8.0-rc.1

Usage

Example