Crate revolt_rocket_okapi
source ·Expand description
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.9.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 revolt_rocket_okapi::{openapi, openapi_get_routes, JsonSchema};
use revolt_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 revolt_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 theopenapi.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 foropenapi.json
)openapi_get_routes_spec![...]
:(Vec<rocket::Route>, okapi::openapi3::OpenApi)
openapi_get_spec![...]
:okapi::openapi3::OpenApi
Re-exports
pub use revolt_okapi;
Modules
Generator
struct, which you can use to manually control the way a struct is
represented in the documentation.Rocket
Handler
s, which are used for serving the json files and the swagger
interface.Rocket
traits pertaining to request
guards and responsesOpenApiResponder
, meaning that a response implementing this trait can be
documented.OpenApiSettings
struct, which can be used to customize the behavior of a
Generator
.Macros
HashMap
with a number of key-value pairs in it.rocket::routes
. This also takes a optional settings object.rocket::routes
. This parses the routes and provides
a tuple with 2 parts (Vec<rocket::Route>, OpenApi)
:OpenApi
spec only, does not generate routes.
This can be used in cases where you are only interested in the openAPI spec, but not in the routes.
A use case could be inside of build.rs
scripts or where you want to alter OpenAPI object
at runtime.Structs
rocket_okapi
when something fails.Traits
Functions
Type Definitions
Result<T, OpenApiError>
.Attribute Macros
Rocket
’s endpoint macros. It requires that all
of the arguments of the route implement one of the traits in rocket_okapi::request
, and that
the return type implements OpenApiResponder
.Derive Macros
OpenApiFromRequest
trait.