Rocket provides code that allows us to build web servers and web based applications such as web APIs. <\/p>\n
We’ll start by just creating a simple endpoint, and then we’ll look at adding Open API and swagger support.<\/p>\n
Starting simple<\/strong><\/p>\n Create yourself a Rust package, for example with cargo<\/p>\n add the following dependency to your Cargo.toml<\/p>\n Now create a Rocket.toml so we can configure rocket’s server and mine looks like this<\/p>\n We need a main.rs (so you can delete the lib.rs if you wish for now) and here’s a very basic starting point<\/p>\n Now, run the application using<\/p>\n As you can see this is a minimal API style, i.e. we create a function supplying it with an HTTP method and we add it to the routes list.<\/p>\n Adding the usual echo endpoint<\/strong><\/p>\n Now let’s add my version of “Hello World” for API’s, a simple echo endpoint.<\/p>\n Now add this to the routes i.e.<\/p>\n Add Open API and Swagger<\/strong><\/p>\n Now we have a couple of simple endpoints, let’s add Open API and Swagger and change the echo endpoint to use Json. I’m purposefully going to keep the index as non-Open API just to demonstrate running both Open API and non-Open API endpoints.<\/p>\n We’re going to need a few addition to our Cargo.toml – now, unfortunately it’s easy to get multiple version dependencies for these, so the one’s shown here will work together without warning\/errors<\/p>\n Notice we’re adding features to the rocket crate and we’ve got some creates for swagger and open api. The schamars<\/em> crate 0.8.22 was being used by other crates, hence I locked this down to the same version.<\/p>\n We’ll extend our echo endpoint to return Json, but before we do I’ll list the use clauses that are listed after #[macro_use] extern crate rocket;<\/em><\/p>\n We’ll create a response object for the echo endpoint and update the echo endpoint to both return this and add the openapi attribute to allow this endpoint to have an open api spec generated for it<\/p>\n Next up we need to change the rocket<\/em> function, so let’s just see the latest version<\/p>\n Now I purposefully left the index route without an open api attribute just to demonstrate, if you have such endpoints, you need to still use the routes!<\/em> macro, if you add index to openapi_get_routes!<\/em> without the open api attribute you’ll get some slight ambiguous error’s such as a function with a similar name exists<\/em>. <\/p>\n Now run your application and go to http:\/\/localhost:8080\/swagger\/index.html and you can interact with your endpoints via the Swagger UI you can also access the openapi.json file using http:\/\/localhost:8080\/openapi.json.<\/p>\n\r\ncargo new myapi --bin\r\n<\/pre>\n
\r\nrocket = "0.5.1"\r\n<\/pre>\n
\r\n[default]\r\nport = 8080\r\naddress = "127.0.0.1"\r\n<\/pre>\n
\r\n#[macro_use] extern crate rocket;\r\n\r\n#[get("\/")]\r\nfn index() -> &'static str {\r\n "Hello, world!"\r\n}\r\n\r\n#[launch]\r\nfn rocket() -> _ {\r\n rocket::build().mount("\/", routes![index])\r\n}\r\n<\/pre>\n\r\ncargo run\r\n<\/pre>\n
\r\n#[get("\/echo?<text>")]\r\nfn echo(text: &str) -> String {\r\n format!("Echo: {}", text)\r\n}\r\n<\/pre>\n\r\n#[launch]\r\nfn rocket() -> _ {\r\n rocket::build().mount("\/", routes![index, echo])\r\n}\r\n<\/pre>\n\r\n[dependencies]\r\nrocket = { version = "0.5.1", features = ["json"] }\r\nopenapi = "0.1.5"\r\nserde = "1.0.219"\r\nrocket_okapi = { version = "0.9.0", features = ["swagger"] }\r\nschemars = "0.8.22"\r\n<\/pre>\n\r\nuse rocket::serde::{Serialize, json::Json};\r\nuse rocket_okapi::{openapi, openapi_get_routes};\r\nuse rocket_okapi::swagger_ui::{make_swagger_ui, SwaggerUIConfig};\r\nuse schemars::JsonSchema;\r\n<\/pre>\n\r\n#[derive(Serialize, JsonSchema)]\r\nstruct EchoResponse {\r\n message: String,\r\n}\r\n\r\n#[openapi]\r\n#[get("\/echo?<text>")]\r\nfn echo(text: &str) -> Json<EchoResponse> {\r\n Json(EchoResponse {\r\n message: format!("Echo: {}", text),\r\n })\r\n}\r\n<\/pre>\n\r\n#[launch]\r\nfn rocket() -> _ {\r\n rocket::build()\r\n .mount("\/", routes![index])\r\n .mount("\/", openapi_get_routes![echo])\r\n .mount(\r\n "\/swagger",\r\n make_swagger_ui(&SwaggerUIConfig {\r\n url: "\/openapi.json".to_owned(),\r\n ..Default::default()\r\n })\r\n )\r\n}\r\n<\/pre>\n