start adding openapi support

Cargo.lock

@@ -194,6 +194,11 @@ dependencies = [
  "lazy_static 1.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "dtoa"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
 [[package]]
 name = "either"
 version = "1.5.3"
@@ -332,9 +337,11 @@ dependencies = [
  "gotham 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "gotham_derive 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "hyper 0.12.35 (registry+https://github.com/rust-lang/crates.io-index)",
+ "indexmap 1.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "log 0.4.8 (registry+https://github.com/rust-lang/crates.io-index)",
  "log4rs 0.8.3 (registry+https://github.com/rust-lang/crates.io-index)",
  "mime 0.3.14 (registry+https://github.com/rust-lang/crates.io-index)",
+ "openapiv3 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "serde 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)",
  "serde_json 1.0.40 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -439,6 +446,9 @@ dependencies = [
 name = "indexmap"
 version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "serde 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)",
+]
 
 [[package]]
 name = "iovec"
@@ -625,6 +635,17 @@ dependencies = [
  "libc 0.2.62 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "openapiv3"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "indexmap 1.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "serde 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)",
+ "serde_json 1.0.40 (registry+https://github.com/rust-lang/crates.io-index)",
+ "serde_yaml 0.8.9 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "owning_ref"
 version = "0.4.0"
@@ -999,6 +1020,17 @@ dependencies = [
  "serde 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "dtoa 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)",
+ "linked-hash-map 0.5.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "serde 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)",
+ "yaml-rust 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "skeptic"
 version = "0.13.4"
@@ -1447,6 +1479,14 @@ dependencies = [
  "winapi-build 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "yaml-rust"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "linked-hash-map 0.5.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [metadata]
 "checksum aho-corasick 0.7.6 (registry+https://github.com/rust-lang/crates.io-index)" = "58fb5e95d83b38284460a5fda7d6470aa0b8844d283a0b614b8535e880800d2d"
 "checksum arc-swap 0.3.11 (registry+https://github.com/rust-lang/crates.io-index)" = "bc4662175ead9cd84451d5c35070517777949a2ed84551764129cedb88384841"
@@ -1472,6 +1512,7 @@ dependencies = [
 "checksum crossbeam-epoch 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)" = "fedcd6772e37f3da2a9af9bf12ebe046c0dfe657992377b4df982a2b54cd37a9"
 "checksum crossbeam-queue 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "7c979cd6cfe72335896575c6b5688da489e420d36a27a0b9eb0c73db574b4a4b"
 "checksum crossbeam-utils 0.6.6 (registry+https://github.com/rust-lang/crates.io-index)" = "04973fa96e96579258a5091af6003abde64af786b860f18622b82e026cca60e6"
+"checksum dtoa 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)" = "ea57b42383d091c85abcc2706240b94ab2a8fa1fc81c10ff23c4de06e2a90b5e"
 "checksum either 1.5.3 (registry+https://github.com/rust-lang/crates.io-index)" = "bb1f6b1ce1c140482ea30ddd3335fc0024ac7ee112895426e0a629a6c20adfe3"
 "checksum error-chain 0.12.1 (registry+https://github.com/rust-lang/crates.io-index)" = "3ab49e9dcb602294bc42f9a7dfc9bc6e936fca4418ea300dbfb84fe16de0b7d9"
 "checksum failure 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)" = "795bd83d3abeb9220f257e597aa0080a508b27533824adf336529648f6abf7e2"
@@ -1518,6 +1559,7 @@ dependencies = [
 "checksum num-integer 0.1.41 (registry+https://github.com/rust-lang/crates.io-index)" = "b85e541ef8255f6cf42bbfe4ef361305c6c135d10919ecc26126c4e5ae94bc09"
 "checksum num-traits 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)" = "6ba9a427cfca2be13aa6f6403b0b7e7368fe982bfa16fccc450ce74c46cd9b32"
 "checksum num_cpus 1.10.1 (registry+https://github.com/rust-lang/crates.io-index)" = "bcef43580c035376c0705c42792c294b66974abbfd2789b511784023f71f3273"
+"checksum openapiv3 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "c8776c7d6a58a03d30ba278adfd54d923eb0a24e26cbf39d2b97648306935d65"
 "checksum owning_ref 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "49a4b8ea2179e6a2e27411d3bca09ca6dd630821cf6894c6c7c8467a8ee7ef13"
 "checksum parking_lot 0.7.1 (registry+https://github.com/rust-lang/crates.io-index)" = "ab41b4aed082705d1056416ae4468b6ea99d52599ecf3169b00088d43113e337"
 "checksum parking_lot_core 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "94c8c7923936b28d546dfd14d4472eaf34c99b14e1c973a32b3e6d4eb04298c9"
@@ -1562,6 +1604,7 @@ dependencies = [
 "checksum serde 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)" = "9796c9b7ba2ffe7a9ce53c2287dfc48080f4b2b362fcc245a259b3a7201119dd"
 "checksum serde_derive 1.0.101 (registry+https://github.com/rust-lang/crates.io-index)" = "4b133a43a1ecd55d4086bd5b4dc6c1751c68b1bfbeba7a5040442022c7e7c02e"
 "checksum serde_json 1.0.40 (registry+https://github.com/rust-lang/crates.io-index)" = "051c49229f282f7c6f3813f8286cc1e3323e8051823fce42c7ea80fe13521704"
+"checksum serde_yaml 0.8.9 (registry+https://github.com/rust-lang/crates.io-index)" = "38b08a9a90e5260fe01c6480ec7c811606df6d3a660415808c3c3fa8ed95b582"
 "checksum skeptic 0.13.4 (registry+https://github.com/rust-lang/crates.io-index)" = "d6fb8ed853fdc19ce09752d63f3a2e5b5158aeb261520cd75eb618bd60305165"
 "checksum slab 0.4.2 (registry+https://github.com/rust-lang/crates.io-index)" = "c111b5bd5695e56cffe5129854aa230b39c93a305372fdbb2668ca2394eea9f8"
 "checksum smallvec 0.6.10 (registry+https://github.com/rust-lang/crates.io-index)" = "ab606a9c5e214920bb66c458cd7be8ef094f813f20fe77a54cc7dbfff220d4b7"
@@ -1611,3 +1654,4 @@ dependencies = [
 "checksum winapi-util 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "7168bab6e1daee33b4557efd0e95d5ca70a03706d39fa5f3fe7a236f584b03c9"
 "checksum winapi-x86_64-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 "checksum ws2_32-sys 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)" = "d59cefebd0c892fa2dd6de581e937301d8552cb44489cdff035c6187cb63fa5e"
+"checksum yaml-rust 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)" = "65923dd1784f44da1d2c3dbbc5e822045628c590ba72123e1c73d3c230c4434d"

Cargo.toml

@@ -21,7 +21,9 @@ futures = "0.1"
 gotham = "0.4"
 gotham_derive = "0.4"
 hyper = "0.12"
+indexmap = { version = "1.0", optional = true }
 mime = "0.3"
+openapiv3 = { version = "0.3", optional = true }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 
@@ -29,3 +31,7 @@ serde_json = "1"
 fake = "2.2"
 log = "0.4"
 log4rs = { version = "0.8", features = ["console_appender"], default-features = false }
+
+[features]
+default = ["openapi"]
+openapi = ["indexmap", "openapiv3"]

src/lib.rs

@@ -3,6 +3,9 @@
 
 pub use hyper::StatusCode;
 
+#[cfg(feature = "openapi")]
+pub mod openapi;
+
 mod resource;
 pub use resource::{
 	Resource,

src/openapi.rs

@@ -0,0 +1,226 @@
+use crate::{
+	resource::*,
+	result::*,
+	routing::*
+};
+use futures::future::{err, ok};
+use gotham::{
+	handler::{HandlerFuture, IntoHandlerError},
+	helpers::http::response::create_response,
+	pipeline::chain::PipelineHandleChain,
+	router::builder::*,
+	state::State
+};
+use indexmap::IndexMap;
+use mime::APPLICATION_JSON;
+use openapiv3::{MediaType, OpenAPI, Operation, PathItem, Paths, ReferenceOr, ReferenceOr::Item, Response, Responses, StatusCode};
+use serde::de::DeserializeOwned;
+use std::panic::RefUnwindSafe;
+
+pub struct OpenapiRouter<'a, D>
+{
+	route : &'a mut D,
+	openapi : OpenAPI
+}
+
+impl<'a, D> OpenapiRouter<'a, D>
+{
+	pub fn new<Title : ToString, Version : ToString>(route : &'a mut D, title : Title, version : Version) -> Self
+	{
+		Self {
+			route,
+			openapi: OpenAPI {
+				openapi: "3.0.2".to_string(),
+				info: openapiv3::Info {
+					title: title.to_string(),
+					description: None,
+					terms_of_service: None,
+					contact: None,
+					license: None,
+					version: version.to_string()
+				},
+				servers: Vec::new(),
+				paths: Paths::new(),
+				components: None,
+				security: Vec::new(),
+				tags: Vec::new(),
+				external_docs: None
+			}
+		}
+	}
+
+	/// Remove path from the OpenAPI spec, or return an empty one if not included. This is handy if you need to
+	/// modify the path and add it back after the modification
+	fn remove_path(&mut self, path : &str) -> PathItem
+	{
+		if let Some(Item(item)) = self.openapi.paths.swap_remove(path)
+		{
+			return item;
+		}
+		return PathItem {
+			get: None,
+			put: None,
+			post: None,
+			delete: None,
+			options: None,
+			head: None,
+			patch: None,
+			trace: None,
+			servers: Vec::new(),
+			parameters: Vec::new()
+		};
+	}
+
+	fn add_path<Path : ToString>(&mut self, path : Path, item : PathItem)
+	{
+		self.openapi.paths.insert(path.to_string(), Item(item));
+	}
+}
+
+fn handle_get_openapi(state : State, openapi : &'static OpenAPI) -> Box<HandlerFuture>
+{
+	let res = serde_json::to_string(openapi);
+	match res {
+		Ok(body) => {
+			let res = create_response(&state, hyper::StatusCode::OK, APPLICATION_JSON, body);
+			Box::new(ok((state, res)))
+		},
+		Err(e) => Box::new(err((state, e.into_handler_error())))
+	}
+}
+
+macro_rules! implOpenapiRouter {
+	($implType:ident) => {
+
+		impl<'a, C, P> OpenapiRouter<'a, $implType<'a, C, P>>
+		where
+			C : PipelineHandleChain<P> + Copy + Send + Sync + 'static,
+			P : RefUnwindSafe + Send + Sync + 'static
+		{
+			pub fn get_openapi(&mut self, path : &str)
+			{
+				let openapi = Box::leak(Box::new(self.openapi.clone()));
+				self.route.get(path).to(|state| {
+					handle_get_openapi(state, openapi)
+				});
+			}
+		}
+		
+		impl<'a, C, P> DrawResources for OpenapiRouter<'a, $implType<'a, C, P>>
+		where
+			C : PipelineHandleChain<P> + Copy + Send + Sync + 'static,
+			P : RefUnwindSafe + Send + Sync + 'static
+		{
+			fn resource<R : Resource, T : ToString>(&mut self, path : T)
+			{
+				R::setup((self, path.to_string()));
+			}
+		}
+
+		impl<'a, C, P> DrawResourceRoutes for (&mut OpenapiRouter<'a, $implType<'a, C, P>>, String)
+		where
+			C : PipelineHandleChain<P> + Copy + Send + Sync + 'static,
+			P : RefUnwindSafe + Send + Sync + 'static
+		{
+			fn read_all<Handler, Res>(&mut self)
+			where
+				Res : ResourceResult,
+				Handler : ResourceReadAll<Res>
+			{
+				let path = &self.1;
+				let mut item = self.0.remove_path(path);
+				let mut content : IndexMap<String, MediaType> = IndexMap::new();
+				content[&APPLICATION_JSON.to_string()] = MediaType {
+					schema: None, // TODO
+					example: None,
+					examples: IndexMap::new(),
+					encoding: IndexMap::new()
+				};
+				let mut responses : IndexMap<StatusCode, ReferenceOr<Response>> = IndexMap::new();
+				responses[&StatusCode::Code(200)] = Item(Response {
+					description: "OK".to_string(),
+					headers: IndexMap::new(),
+					content,
+					links: IndexMap::new()
+				});
+				item.get = Some(Operation {
+					tags: Vec::new(),
+					summary: None,
+					description: None,
+					external_documentation: None,
+					operation_id: None, // TODO
+					parameters: Vec::new(),
+					request_body: None,
+					responses: Responses {
+						default: None,
+						responses
+					},
+					deprecated: false,
+					security: Vec::new(),
+					servers: Vec::new()
+				});
+				self.0.add_path(path, item);
+				
+				(&mut *self.0.route, self.1.to_string()).read_all::<Handler, Res>()
+			}
+			
+			fn read<Handler, ID, Res>(&mut self)
+			where
+				ID : DeserializeOwned + Clone + RefUnwindSafe + Send + Sync + 'static,
+				Res : ResourceResult,
+				Handler : ResourceRead<ID, Res>
+			{
+				(&mut *self.0.route, self.1.to_string()).read::<Handler, ID, Res>()
+			}
+			
+			fn create<Handler, Body, Res>(&mut self)
+			where
+				Body : DeserializeOwned,
+				Res : ResourceResult,
+				Handler : ResourceCreate<Body, Res>
+			{
+				(&mut *self.0.route, self.1.to_string()).create::<Handler, Body, Res>()
+			}
+			
+			fn update_all<Handler, Body, Res>(&mut self)
+			where
+				Body : DeserializeOwned,
+				Res : ResourceResult,
+				Handler : ResourceUpdateAll<Body, Res>
+			{
+				(&mut *self.0.route, self.1.to_string()).update_all::<Handler, Body, Res>()
+			}
+			
+			fn update<Handler, ID, Body, Res>(&mut self)
+			where
+				ID : DeserializeOwned + Clone + RefUnwindSafe + Send + Sync + 'static,
+				Body : DeserializeOwned,
+				Res : ResourceResult,
+				Handler : ResourceUpdate<ID, Body, Res>
+			{
+				(&mut *self.0.route, self.1.to_string()).update::<Handler, ID, Body, Res>()
+			}
+			
+			fn delete_all<Handler, Res>(&mut self)
+			where
+				Res : ResourceResult,
+				Handler : ResourceDeleteAll<Res>
+			{
+				(&mut *self.0.route, self.1.to_string()).delete_all::<Handler, Res>()
+			}
+			
+			fn delete<Handler, ID, Res>(&mut self)
+			where
+				ID : DeserializeOwned + Clone + RefUnwindSafe + Send + Sync + 'static,
+				Res : ResourceResult,
+				Handler : ResourceDelete<ID, Res>
+			{
+				(&mut *self.0.route, self.1.to_string()).delete::<Handler, ID, Res>()
+			}
+		}
+
+	}
+}
+
+implOpenapiRouter!(RouterBuilder);
+implOpenapiRouter!(ScopeBuilder);

src/routing.rs

@@ -3,6 +3,9 @@ use crate::{
 	result::{ResourceError, ResourceResult},
 	StatusCode
 };
+#[cfg(feature = "openapi")]
+use crate::openapi::OpenapiRouter;
+
 use futures::{
 	future::{Future, err, ok},
 	stream::Stream
@@ -25,6 +28,19 @@ struct PathExtractor<ID : RefUnwindSafe + Send + 'static>
 	id : ID
 }
 
+/// This trait adds the `with_openapi` method to gotham's routing. It turns the default
+/// router into one that will only allow RESTful resources, but record them and generate
+/// an OpenAPI specification on request.
+#[cfg(feature = "openapi")]
+pub trait WithOpenapi<D>
+{
+	fn with_openapi<F, Title, Version>(&mut self, title : Title, version : Version, block : F)
+	where
+		F : FnOnce(OpenapiRouter<D>),
+		Title : ToString,
+		Version : ToString;
+}
+
 /// This trait adds the `resource` method to gotham's routing. It allows you to register
 /// any RESTful `Resource` with a path.
 pub trait DrawResources
@@ -212,6 +228,24 @@ where
 
 macro_rules! implDrawResourceRoutes {
 	($implType:ident) => {
+		
+		#[cfg(feature = "openapi")]
+		impl<'a, C, P> WithOpenapi<Self> for $implType<'a, C, P>
+		where
+			C : PipelineHandleChain<P> + Copy + Send + Sync + 'static,
+			P : RefUnwindSafe + Send + Sync + 'static
+		{
+			fn with_openapi<F, Title, Version>(&mut self, title : Title, version : Version, block : F)
+			where
+				F : FnOnce(OpenapiRouter<Self>),
+				Title : ToString,
+				Version : ToString
+			{
+				let router : OpenapiRouter<Self> = OpenapiRouter::new(self, title, version);
+				block(router);
+			}
+		}
+		
 		impl<'a, C, P> DrawResources for $implType<'a, C, P>
 		where
 			C : PipelineHandleChain<P> + Copy + Send + Sync + 'static,