Add swagger for some endpoints

aw-client-rust/src/lib.rs

@@ -1,7 +1,6 @@
+extern crate aw_models;
 extern crate gethostname;
 extern crate reqwest;
-#[macro_use]
-extern crate aw_models;
 extern crate serde_json;
 
 use std::collections::HashMap;

aw-models/src/timeinterval.rs

@@ -1,6 +1,8 @@
 use std::fmt;
 
-use serde::de::{self, Deserialize, Deserializer, Visitor};
+use serde::de::Error as DeserializeError;
+use serde::de::Visitor;
+use serde::{Deserialize, Deserializer};
 
 use chrono::DateTime;
 use chrono::Duration;
@@ -72,13 +74,16 @@ impl<'de> Visitor<'de> for TimeIntervalVisitor {
 
     fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
     where
-        E: de::Error,
+        E: DeserializeError,
     {
         match TimeInterval::new_from_string(&value) {
             Ok(ti) => Ok(ti),
             Err(e) => {
                 warn!("{:?}", e);
-                Err(de::Error::invalid_value(Unexpected::Str(value), &self))
+                Err(DeserializeError::invalid_value(
+                    Unexpected::Str(value),
+                    &self,
+                ))
             }
         }
     }

aw-server/Cargo.toml

@@ -29,6 +29,9 @@ toml = "0.5"
 gethostname = "0.2"
 uuid = { version = "0.8", features = ["serde", "v4"] }
 getopts = "0.2"
+rocket_okapi = "0.5"
+schemars = "0.7"
+okapi = { version = "0.4", features = ["derive_json_schema"] }
 
 aw-datastore = { path = "../aw-datastore" }
 aw-models = { path = "../aw-models" }

aw-server/src/endpoints/bucket.rs

@@ -1,5 +1,4 @@
 use std::collections::HashMap;
-use std::io::Cursor;
 
 use rocket_contrib::json::Json;
 
@@ -10,13 +9,13 @@ use aw_models::Bucket;
 use aw_models::BucketsExport;
 use aw_models::Event;
 
-use rocket::http::Header;
 use rocket::http::Status;
-use rocket::response::Response;
 use rocket::State;
+use rocket_okapi::openapi;
 
 use crate::endpoints::{HttpErrorJson, ServerState};
 
+#[openapi]
 #[get("/")]
 pub fn buckets_get(
     state: State<ServerState>,
@@ -28,6 +27,7 @@ pub fn buckets_get(
     }
 }
 
+#[openapi]
 #[get("/<bucket_id>")]
 pub fn bucket_get(
     bucket_id: String,
@@ -40,6 +40,7 @@ pub fn bucket_get(
     }
 }
 
+#[openapi]
 #[post("/<bucket_id>", data = "<message>", format = "application/json")]
 pub fn bucket_new(
     bucket_id: String,
@@ -58,6 +59,7 @@ pub fn bucket_new(
     }
 }
 
+#[openapi]
 #[get("/<bucket_id>/events?<start>&<end>&<limit>")]
 pub fn bucket_events_get(
     bucket_id: String,
@@ -102,6 +104,7 @@ pub fn bucket_events_get(
     }
 }
 
+#[openapi]
 #[post("/<bucket_id>/events", data = "<events>", format = "application/json")]
 pub fn bucket_events_create(
     bucket_id: String,
@@ -116,6 +119,7 @@ pub fn bucket_events_create(
     }
 }
 
+#[openapi]
 #[post(
     "/<bucket_id>/heartbeat?<pulsetime>",
     data = "<heartbeat_json>",
@@ -135,6 +139,7 @@ pub fn bucket_events_heartbeat(
     }
 }
 
+#[openapi]
 #[get("/<bucket_id>/events/count")]
 pub fn bucket_event_count(
     bucket_id: String,
@@ -148,6 +153,7 @@ pub fn bucket_event_count(
     }
 }
 
+#[openapi]
 #[delete("/<bucket_id>/events/<event_id>")]
 pub fn bucket_events_delete_by_id(
     bucket_id: String,
@@ -161,11 +167,12 @@ pub fn bucket_events_delete_by_id(
     }
 }
 
+#[openapi]
 #[get("/<bucket_id>/export")]
 pub fn bucket_export(
     bucket_id: String,
     state: State<ServerState>,
-) -> Result<Response, HttpErrorJson> {
+) -> Result<Json<BucketsExport>, HttpErrorJson> {
     let datastore = endpoints_get_lock!(state.datastore);
     let mut export = BucketsExport {
         buckets: HashMap::new(),
@@ -180,8 +187,10 @@ pub fn bucket_export(
             .expect("Failed to get events for bucket"),
     );
     export.buckets.insert(bucket_id.clone(), bucket);
-    let filename = format!("aw-bucket-export_{}.json", bucket_id);
 
+    // TODO: Add back Content-Disposition
+    /*
+    let filename = format!("aw-bucket-export_{}.json", bucket_id);
     let header_content = format!("attachment; filename={}", filename);
     Ok(Response::build()
         .status(Status::Ok)
@@ -190,8 +199,11 @@ pub fn bucket_export(
             serde_json::to_string(&export).expect("Failed to serialize"),
         ))
         .finalize())
+    */
+    Ok(Json(export))
 }
 
+#[openapi]
 #[delete("/<bucket_id>")]
 pub fn bucket_delete(bucket_id: String, state: State<ServerState>) -> Result<(), HttpErrorJson> {
     let datastore = endpoints_get_lock!(state.datastore);

aw-server/src/endpoints/export.rs

@@ -1,17 +1,17 @@
 use std::collections::HashMap;
-use std::io::Cursor;
 
-use rocket::http::Header;
 use rocket::http::Status;
-use rocket::response::Response;
 use rocket::State;
+use rocket_contrib::json::Json;
+use rocket_okapi::openapi;
 
 use aw_models::BucketsExport;
 
 use crate::endpoints::{HttpErrorJson, ServerState};
 
+#[openapi]
 #[get("/")]
-pub fn buckets_export(state: State<ServerState>) -> Result<Response, HttpErrorJson> {
+pub fn buckets_export(state: State<ServerState>) -> Result<Json<BucketsExport>, HttpErrorJson> {
     let datastore = endpoints_get_lock!(state.datastore);
     let mut export = BucketsExport {
         buckets: HashMap::new(),
@@ -28,6 +28,7 @@ pub fn buckets_export(state: State<ServerState>) -> Result<Response, HttpErrorJs
         export.buckets.insert(bid, bucket);
     }
 
+    /*
     Ok(Response::build()
         .status(Status::Ok)
         .header(Header::new(
@@ -38,4 +39,6 @@ pub fn buckets_export(state: State<ServerState>) -> Result<Response, HttpErrorJs
             serde_json::to_string(&export).expect("Failed to serialize"),
         ))
         .finalize())
+    */
+    Ok(Json(export))
 }

aw-server/src/endpoints/import.rs

@@ -1,11 +1,10 @@
+use multipart::server::Multipart;
 use rocket::http::ContentType;
 use rocket::http::Status;
 use rocket::Data;
 use rocket::State;
 use rocket_contrib::json::Json;
 
-use multipart::server::Multipart;
-
 use std::io::Read;
 use std::sync::Mutex;
 

aw-server/src/endpoints/mod.rs

@@ -2,9 +2,12 @@ use std::path::PathBuf;
 use std::sync::Mutex;
 
 use gethostname::gethostname;
+use rocket::get;
 use rocket::response::NamedFile;
 use rocket::State;
 use rocket_contrib::json::Json;
+use rocket_okapi::swagger_ui::{make_swagger_ui, SwaggerUIConfig};
+use rocket_okapi::{openapi, routes_with_openapi};
 
 use crate::config::AWConfig;
 
@@ -58,6 +61,7 @@ fn root_favicon(state: State<ServerState>) -> Option<NamedFile> {
     NamedFile::open(state.asset_path.join("favicon.ico")).ok()
 }
 
+#[openapi]
 #[get("/")]
 fn server_info(config: State<AWConfig>, state: State<ServerState>) -> Json<Info> {
     #[allow(clippy::or_fun_call)]
@@ -72,6 +76,20 @@ fn server_info(config: State<AWConfig>, state: State<ServerState>) -> Json<Info>
     })
 }
 
+fn get_docs() -> SwaggerUIConfig {
+    use rocket_okapi::swagger_ui::UrlObject;
+
+    SwaggerUIConfig {
+        url: "/info/openapi.json".to_string(),
+        urls: vec![
+            UrlObject::new("Info", "/api/0/info/openapi.json"),
+            UrlObject::new("Bucket", "/api/0/buckets/openapi.json"),
+            UrlObject::new("Export", "/api/0/export/openapi.json"),
+        ],
+        ..Default::default()
+    }
+}
+
 pub fn build_rocket(server_state: ServerState, config: AWConfig) -> rocket::Rocket {
     info!(
         "Starting aw-server-rust at {}:{}",
@@ -89,10 +107,10 @@ pub fn build_rocket(server_state: ServerState, config: AWConfig) -> rocket::Rock
                 root_static,
             ],
         )
-        .mount("/api/0/info", routes![server_info])
+        .mount("/api/0/info", routes_with_openapi![server_info])
         .mount(
             "/api/0/buckets",
-            routes![
+            routes_with_openapi![
                 bucket::bucket_new,
                 bucket::bucket_delete,
                 bucket::buckets_get,
@@ -110,7 +128,10 @@ pub fn build_rocket(server_state: ServerState, config: AWConfig) -> rocket::Rock
             "/api/0/import",
             routes![import::bucket_import_json, import::bucket_import_form],
         )
-        .mount("/api/0/export", routes![export::buckets_export])
+        .mount(
+            "/api/0/export",
+            routes_with_openapi![export::buckets_export],
+        )
         .mount(
             "/api/0/settings",
             routes![
@@ -120,6 +141,7 @@ pub fn build_rocket(server_state: ServerState, config: AWConfig) -> rocket::Rock
                 settings::setting_delete
             ],
         )
+        .mount("/api", make_swagger_ui(&get_docs()))
         .attach(cors::cors(&config))
         .manage(server_state)
         .manage(config)

aw-server/src/endpoints/util.rs

@@ -4,11 +4,13 @@ use rocket::http::ContentType;
 use rocket::http::Status;
 use rocket::request::Request;
 use rocket::response::{self, Responder, Response};
+use rocket_okapi::JsonSchema;
 use serde::Serialize;
 
-#[derive(Serialize, Debug)]
+#[derive(Serialize, JsonSchema, Debug)]
 pub struct HttpErrorJson {
-    #[serde(skip_serializing)]
+    #[serde(skip)]
+    #[schemars(skip)]
     status: Status,
     message: String,
 }
@@ -34,6 +36,20 @@ impl<'r> Responder<'r> for HttpErrorJson {
     }
 }
 
+use std::collections::BTreeMap;
+
+impl<'r> rocket_okapi::response::OpenApiResponder<'r> for HttpErrorJson {
+    fn responses(
+        _gen: &mut rocket_okapi::gen::OpenApiGenerator,
+    ) -> Result<okapi::openapi3::Responses, rocket_okapi::OpenApiError> {
+        Ok(okapi::openapi3::Responses {
+            default: None,
+            responses: BTreeMap::new(),
+            extensions: BTreeMap::new(),
+        })
+    }
+}
+
 use aw_datastore::DatastoreError;
 
 impl Into<HttpErrorJson> for DatastoreError {