implement auto-documenting routes

core/codegen/src/attribute/route/mod.rs

@@ -319,6 +319,9 @@ fn codegen_route(route: Route) -> Result<TokenStream> {
  let rank = Optional(route.attr.rank);
  let format = Optional(route.attr.format.as_ref());
 
+ // Get the doc comment
+ let docstring = &route.docstring;
+
  Ok(quote! {
  #handler_fn
 
@@ -353,6 +356,7 @@ fn codegen_route(route: Route) -> Result<TokenStream> {
  format: #format,
  rank: #rank,
  sentinels: #sentinels,
+ docstring: #docstring,
  }
  }
 

core/codegen/src/attribute/route/parse.rs

@@ -29,6 +29,8 @@ pub struct Route {
  pub handler: syn::ItemFn,
  /// The parsed arguments to the user's function.
  pub arguments: Arguments,
+ /// The doc comment describing this route
+ pub docstring: String,
 }
 
 type ArgumentMap = IndexMap<Name, (syn::Ident, syn::Type)>;
@@ -209,9 +211,11 @@ impl Route {
  })
  .collect();
 
+ let docstring = String::from_attrs("doc", &handler.attrs)?.join("\n");
+
  diags.head_err_or(Route {
  attr, path_params, query_params, data_guard, request_guards,
- handler, arguments,
+ handler, arguments, docstring
  })
  }
 }

core/lib/src/doc/has_schema.rs

@@ -0,0 +1,285 @@
+pub enum SchemaKind {
+ Null,
+ Map,
+ List,
+ String,
+ Num,
+ Int,
+ Bool,
+ Set,
+}
+
+pub struct Schema<T> {
+ pub description: Option<String>,
+ pub example: Option<T>,
+ pub name: String,
+ pub kind: SchemaKind,
+
+}
+
+pub trait HasSchema: Sized {
+ fn schema() -> Schema<Self>;
+}
+
+// impls for the entire serde data model:
+
+// 14 primitve types
+impl HasSchema for i8 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "signed 8-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for i16 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "signed 16-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for i32 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "signed 32-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for i64 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "signed 64-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for i128 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "signed 128-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for u8 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "unsigned 8-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for u16 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "unsigned 16-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for u32 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "unsigned 32-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for u64 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "unsigned 64-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+impl HasSchema for u128 {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(1),
+ name: "unsigned 128-bits integer".to_string(),
+ kind: SchemaKind::Int,
+ }
+ }
+}
+
+// string
+impl<'a> HasSchema for &'a str {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some("string"),
+ name: "signed 8-bits integer".to_string(),
+ kind: SchemaKind::String,
+ }
+ }
+}
+
+impl<'a> HasSchema for String {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some("string".to_string()),
+ name: "signed 8-bits integer".to_string(),
+ kind: SchemaKind::String,
+ }
+ }
+}
+
+// byte array
+impl<'a> HasSchema for &'a [u8] {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: None,
+ name: "An array of bytes".to_string(),
+ kind: SchemaKind::List,
+ }
+ }
+}
+
+// option
+impl<T: HasSchema> HasSchema for Option<T> {
+ fn schema() -> Schema<Self> {
+ let base_schema = T::schema();
+ Schema {
+ description: None,
+ example: Some(base_schema.example),
+ name: format!("Optional: {}", base_schema.name),
+ kind: base_schema.kind,
+ }
+ }
+}
+
+// unit
+impl HasSchema for () {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: Some(()),
+ name: "Nothing".to_string(),
+ kind: SchemaKind::Null,
+ }
+ }
+}
+
+// seq
+impl<T: HasSchema, const N: usize> HasSchema for [T; N] {
+ fn schema() -> Schema<Self> {
+ let base_schema = T::schema();
+ Schema {
+ description: None,
+ example: None, // making an array example requires that T be Copy...
+ name: format!("Array of {} {}'s", N, base_schema.name),
+ kind: SchemaKind::List,
+ }
+ }
+}
+
+impl<T: HasSchema> HasSchema for Vec<T> {
+ fn schema() -> Schema<Self> {
+ let base_schema = T::schema();
+ Schema {
+ description: None,
+ example: None, // making an array example requires that T be Copy...
+ name: format!("Unsized array of {}'s", base_schema.name),
+ kind: SchemaKind::List,
+ }
+ }
+}
+
+impl<T: HasSchema> HasSchema for std::collections::HashSet<T> {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: None, // making an array example requires that T be Copy...
+ name: format!("Set of {}'s", T::schema().name),
+ kind: SchemaKind::Set,
+ }
+ }
+}
+
+// tuple
+impl<T1: HasSchema> HasSchema for (T1, ) {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: None, // making an array example requires that T be Copy...
+ name: format!("Unary tuple of an {}", T1::schema().name),
+ kind: SchemaKind::Set,
+ }
+ }
+}
+
+impl<T1: HasSchema, T2: HasSchema> HasSchema for (T1, T2) {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: None, // making an array example requires that T be Copy...
+ name: format!("Tuple of the form ({}, {})", T1::schema().name, T2::schema().name),
+ kind: SchemaKind::Set,
+ }
+ }
+}
+
+// todo: extend with macros
+
+// map
+impl<K: HasSchema, V: HasSchema> HasSchema for std::collections::HashMap<K, V> {
+ fn schema() -> Schema<Self> {
+ Schema {
+ description: None,
+ example: None, // making an array example requires that T be Copy...
+ name: format!("Map from {} to {}", K::schema().name, V::schema().name),
+ kind: SchemaKind::Map,
+ }
+ }
+}
+
+
+
+// impl<T: HasSchema> HasSchema for Box<T> {
+// fn schema() -> Schema<Self> {
+// let base_schema = T::schema();
+// Schema {
+// description: base_schema.description,
+// example: base_schema.example.map(Box::new),
+// name: base_schema.name,
+// kind: base_schema.kind,
+// }
+// }
+// }
+
+
+

core/lib/src/doc/mod.rs

@@ -0,0 +1,48 @@
+//! Traits and structs related to automagically generating documentation for your Rocket routes
+
+use std::{collections::HashMap, marker::PhantomData};
+
+use rocket_http::ContentType;
+
+mod has_schema;
+
+#[derive(Default)]
+pub struct Docs(HashMap<ContentType, DocContent>);
+
+#[derive(Default)]
+pub struct DocContent {
+ title: Option<String>,
+ description: Option<String>,
+ content_type: Option<String>,
+}
+
+pub struct Resolve<T: ?Sized>(PhantomData<T>);
+
+pub trait Documented {
+ fn docs() -> Docs;
+}
+
+trait Undocumented {
+ fn docs() -> Docs {
+ Docs::default()
+ }
+}
+
+impl<T: ?Sized> Undocumented for T { }
+
+impl<T: Documented + ?Sized> Resolve<T> {
+ pub const DOCUMENTED: bool = true;
+
+ pub fn docs() -> Docs {
+ T::docs()
+ }
+}
+
+// impl<T: Documented + ?Sized> Documented for Json<T> {
+// fn docs() -> Docs {
+// Docs {
+// content_type: Some("application/json".to_string()),
+// ..Self::docs()
+// }
+// }
+// }

core/lib/src/lib.rs

@@ -124,6 +124,7 @@ pub mod fairing;
 pub mod error;
 pub mod catcher;
 pub mod route;
+pub mod doc;
 
 // Reexport of HTTP everything.
 pub mod http {