Add macro to simplify nesting route specs (#138)

* Add `get_nested_endpoints_and_docs` macro
* Add nested example

Cargo.toml

@@ -5,6 +5,7 @@ members = [
  "rocket-okapi-codegen",
  "examples/json-web-api",
  "examples/custom_schema",
+ "examples/nested",
  "examples/uuid_usage",
  "examples/special-types",
  "examples/secure_request_guard",

examples/nested/.gitignore

@@ -0,0 +1,4 @@
+/target
+**/*.rs.bk
+Cargo.lock
+/.idea

examples/nested/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "nested"
+version = "0.1.0"
+authors = ["Maxime Borges <[email protected]>", "Ralph Bisschops <[email protected]>"]
+edition = "2021"
+
+[dependencies]
+rocket = { version = "=0.5.0", default-features = false, features = ["json"] }
+rocket_okapi = { path = "../../rocket-okapi", features = ["rapidoc"] }
+serde = "1.0"
+serde_json = "1.0"
+indexmap = "1.8.2"

examples/nested/src/api/message.rs

@@ -0,0 +1,42 @@
+use rocket::form::FromForm;
+use rocket::{get, post, serde::json::Json};
+use rocket_okapi::okapi::openapi3::OpenApi;
+use rocket_okapi::okapi::schemars::{self, JsonSchema};
+use rocket_okapi::openapi;
+use rocket_okapi::openapi_get_routes_spec;
+use rocket_okapi::settings::OpenApiSettings;
+use serde::{Deserialize, Serialize};
+
+pub fn get_routes_and_docs(settings: &OpenApiSettings) -> (Vec<rocket::Route>, OpenApi) {
+ openapi_get_routes_spec![settings: create_message, get_message]
+}
+
+#[derive(Serialize, Deserialize, JsonSchema, FromForm)]
+struct Message {
+ /// The unique identifier for the message.
+ message_id: u64,
+ /// Content of the message.
+ content: String,
+}
+
+/// # Create a message
+///
+/// Returns the created message.
+#[openapi(tag = "Message")]
+#[post("/", data = "<message>")]
+fn create_message(message: crate::DataResult<'_, Message>) -> crate::Result<Message> {
+ let message = message?.into_inner();
+ Ok(Json(message))
+}
+
+/// # Get a message by id
+///
+/// Returns the message with the requested id.
+#[openapi(tag = "Message")]
+#[get("/<id>")]
+fn get_message(id: u64) -> crate::Result<Message> {
+ Ok(Json(Message {
+ message_id: id,
+ content: "Hey, how are you?".to_owned(),
+ }))
+}

examples/nested/src/api/mod.rs

@@ -0,0 +1,13 @@
+mod message;
+mod post;
+
+use rocket_okapi::{
+ get_nested_endpoints_and_docs, okapi::openapi3::OpenApi, settings::OpenApiSettings,
+};
+
+pub fn get_routes_and_docs(settings: &OpenApiSettings) -> (Vec<rocket::Route>, OpenApi) {
+ get_nested_endpoints_and_docs! {
+ "/posts" => post::get_routes_and_docs(settings),
+ "/message" => message::get_routes_and_docs(settings),
+ }
+}

examples/nested/src/api/post.rs

@@ -0,0 +1,45 @@
+use rocket::form::FromForm;
+use rocket::{get, post, serde::json::Json};
+use rocket_okapi::okapi::openapi3::OpenApi;
+use rocket_okapi::okapi::schemars::{self, JsonSchema};
+use rocket_okapi::openapi;
+use rocket_okapi::openapi_get_routes_spec;
+use rocket_okapi::settings::OpenApiSettings;
+use serde::{Deserialize, Serialize};
+
+pub fn get_routes_and_docs(settings: &OpenApiSettings) -> (Vec<rocket::Route>, OpenApi) {
+ openapi_get_routes_spec![settings: create_post, get_post]
+}
+
+#[derive(Serialize, Deserialize, JsonSchema, FromForm)]
+struct Post {
+ /// The unique identifier for the post.
+ post_id: u64,
+ /// The title of the post.
+ title: String,
+ /// A short summary of the post.
+ summary: Option<String>,
+}
+
+/// # Create post
+///
+/// Returns the created post.
+#[openapi(tag = "Posts")]
+#[post("/", data = "<post>")]
+fn create_post(post: crate::DataResult<'_, Post>) -> crate::Result<Post> {
+ let post = post?.into_inner();
+ Ok(Json(post))
+}
+
+/// # Get a post by id
+///
+/// Returns the post with the requested id.
+#[openapi(tag = "Posts")]
+#[get("/<id>")]
+fn get_post(id: u64) -> crate::Result<Post> {
+ Ok(Json(Post {
+ post_id: id,
+ title: "Your post".to_owned(),
+ summary: Some("Best summary ever.".to_owned()),
+ }))
+}

examples/nested/src/error.rs

@@ -0,0 +1,117 @@
+use rocket::{
+ http::{ContentType, Status},
+ request::Request,
+ response::{self, Responder, Response},
+};
+use rocket_okapi::okapi::openapi3::Responses;
+use rocket_okapi::okapi::schemars::{self, Map};
+use rocket_okapi::{gen::OpenApiGenerator, response::OpenApiResponderInner, OpenApiError};
+
+/// Error messages returned to user
+#[derive(Debug, serde::Serialize, schemars::JsonSchema)]
+pub struct Error {
+ /// The title of the error message
+ pub err: String,
+ /// The description of the error
+ pub msg: Option<String>,
+ // HTTP Status Code returned
+ #[serde(skip)]
+ pub http_status_code: u16,
+}
+
+impl OpenApiResponderInner for Error {
+ fn responses(_generator: &mut OpenApiGenerator) -> Result<Responses, OpenApiError> {
+ use rocket_okapi::okapi::openapi3::{RefOr, Response as OpenApiReponse};
+
+ let mut responses = Map::new();
+ responses.insert(
+ "400".to_string(),
+ RefOr::Object(OpenApiReponse {
+ description: "\
+ # [400 Bad Request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400)\n\
+ The request given is wrongly formatted or data asked could not be fulfilled. \
+ "
+ .to_string(),
+ ..Default::default()
+ }),
+ );
+ responses.insert(
+ "404".to_string(),
+ RefOr::Object(OpenApiReponse {
+ description: "\
+ # [404 Not Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404)\n\
+ This response is given when you request a page that does not exists.\
+ "
+ .to_string(),
+ ..Default::default()
+ }),
+ );
+ responses.insert(
+ "422".to_string(),
+ RefOr::Object(OpenApiReponse {
+ description: "\
+ # [422 Unprocessable Entity](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422)\n\
+ This response is given when you request body is not correctly formatted. \
+ ".to_string(),
+ ..Default::default()
+ }),
+ );
+ responses.insert(
+ "500".to_string(),
+ RefOr::Object(OpenApiReponse {
+ description: "\
+ # [500 Internal Server Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500)\n\
+ This response is given when something wend wrong on the server. \
+ ".to_string(),
+ ..Default::default()
+ }),
+ );
+ Ok(Responses {
+ responses,
+ ..Default::default()
+ })
+ }
+}
+
+impl std::fmt::Display for Error {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ write!(
+ formatter,
+ "Error `{}`: {}",
+ self.err,
+ self.msg.as_deref().unwrap_or("<no message>")
+ )
+ }
+}
+
+impl std::error::Error for Error {}
+
+impl<'r> Responder<'r, 'static> for Error {
+ fn respond_to(self, _: &'r Request<'_>) -> response::Result<'static> {
+ // Convert object to json
+ let body = serde_json::to_string(&self).unwrap();
+ Response::build()
+ .sized_body(body.len(), std::io::Cursor::new(body))
+ .header(ContentType::JSON)
+ .status(Status::new(self.http_status_code))
+ .ok()
+ }
+}
+
+impl From<rocket::serde::json::Error<'_>> for Error {
+ fn from(err: rocket::serde::json::Error) -> Self {
+ use rocket::serde::json::Error::*;
+ match err {
+ Io(io_error) => Error {
+ err: "IO Error".to_owned(),
+ msg: Some(io_error.to_string()),
+ http_status_code: 422,
+ },
+ Parse(_raw_data, parse_error) => Error {
+ err: "Parse Error".to_owned(),
+ msg: Some(parse_error.to_string()),
+ http_status_code: 422,
+ },
+ }
+ }
+}

examples/nested/src/main.rs

@@ -0,0 +1,128 @@
+use rocket::{Build, Rocket};
+use rocket_okapi::okapi::openapi3::OpenApi;
+use rocket_okapi::settings::UrlObject;
+use rocket_okapi::{mount_endpoints_and_merged_docs, rapidoc::*};
+
+mod api;
+mod error;
+
+pub type Result<T> = std::result::Result<rocket::serde::json::Json<T>, error::Error>;
+pub type DataResult<'a, T> =
+ std::result::Result<rocket::serde::json::Json<T>, rocket::serde::json::Error<'a>>;
+
+#[rocket::main]
+async fn main() {
+ let launch_result = create_server().launch().await;
+ match launch_result {
+ Ok(_) => println!("Rocket shut down gracefully."),
+ Err(err) => println!("Rocket had an error: {}", err),
+ };
+}
+
+pub fn create_server() -> Rocket<Build> {
+ let mut building_rocket = rocket::build().mount(
+ "/rapidoc/",
+ make_rapidoc(&RapiDocConfig {
+ title: Some("My special documentation | RapiDoc".to_owned()),
+ general: GeneralConfig {
+ spec_urls: vec![UrlObject::new("General", "../v1/openapi.json")],
+ ..Default::default()
+ },
+ hide_show: HideShowConfig {
+ allow_spec_url_load: false,
+ allow_spec_file_load: false,
+ ..Default::default()
+ },
+ ..Default::default()
+ }),
+ );
+
+ let openapi_settings = rocket_okapi::settings::OpenApiSettings::default();
+ let custom_route_spec = (vec![], custom_openapi_spec());
+ mount_endpoints_and_merged_docs! {
+ building_rocket, "/v1".to_owned(), openapi_settings,
+ "/external" => custom_route_spec,
+ "/api" => api::get_routes_and_docs(&openapi_settings),
+ };
+
+ building_rocket
+}
+
+fn custom_openapi_spec() -> OpenApi {
+ use indexmap::indexmap;
+ use rocket_okapi::okapi::openapi3::*;
+ use rocket_okapi::okapi::schemars::schema::*;
+ OpenApi {
+ openapi: OpenApi::default_version(),
+ info: Info {
+ title: "The best API ever".to_owned(),
+ description: Some("This is the best API ever, please use me!".to_owned()),
+ terms_of_service: Some(
+ "https://github.com/GREsau/okapi/blob/master/LICENSE".to_owned(),
+ ),
+ contact: Some(Contact {
+ name: Some("okapi example".to_owned()),
+ url: Some("https://github.com/GREsau/okapi".to_owned()),
+ email: None,
+ ..Default::default()
+ }),
+ license: Some(License {
+ name: "MIT".to_owned(),
+ url: Some("https://github.com/GREsau/okapi/blob/master/LICENSE".to_owned()),
+ ..Default::default()
+ }),
+ version: env!("CARGO_PKG_VERSION").to_owned(),
+ ..Default::default()
+ },
+ servers: vec![
+ Server {
+ url: "http://127.0.0.1:8000/".to_owned(),
+ description: Some("Localhost".to_owned()),
+ ..Default::default()
+ },
+ Server {
+ url: "https://example.com/".to_owned(),
+ description: Some("Possible Remote".to_owned()),
+ ..Default::default()
+ },
+ ],
+ // Add paths that do not exist in Rocket (or add extra info to existing paths)
+ paths: {
+ indexmap! {
+ "/home".to_owned() => PathItem{
+ get: Some(
+ Operation {
+ tags: vec!["HomePage".to_owned()],
+ summary: Some("This is my homepage".to_owned()),
+ responses: Responses{
+ responses: indexmap!{
+ "200".to_owned() => RefOr::Object(
+ Response{
+ description: "Return the page, no error.".to_owned(),
+ content: indexmap!{
+ "text/html".to_owned() => MediaType{
+ schema: Some(SchemaObject{
+ instance_type: Some(SingleOrVec::Single(Box::new(
+ InstanceType::String
+ ))),
+ ..Default::default()
+ }),
+ ..Default::default()
+ }
+ },
+ ..Default::default()
+ }
+ )
+ },
+ ..Default::default()
+ },
+ ..Default::default()
+ }
+ ),
+ ..Default::default()
+ }
+ }
+ },
+ ..Default::default()
+ }
+}