Attribute for defining examples (#23)

schemars/tests/examples.rs

@@ -0,0 +1,25 @@
+mod util;
+use schemars::JsonSchema;
+use serde::Serialize;
+use util::*;
+
+#[derive(Default, Debug, JsonSchema, Serialize)]
+#[schemars(example = "Struct::default", example = "null")]
+pub struct Struct {
+ #[schemars(example = "eight", example = "null")]
+ foo: i32,
+ bar: bool,
+ #[schemars(example = "null")]
+ baz: Option<&'static str>,
+}
+
+fn eight() -> i32 {
+ 8
+}
+
+fn null() -> () {}
+
+#[test]
+fn examples() -> TestResult {
+ test_default_generated_schema::<Struct>("examples")
+}

schemars/tests/expected/examples.json

@@ -0,0 +1,39 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Struct",
+ "examples": [
+ {
+ "bar": false,
+ "baz": null,
+ "foo": 0
+ },
+ null
+ ],
+ "type": "object",
+ "required": [
+ "bar",
+ "foo"
+ ],
+ "properties": {
+ "bar": {
+ "type": "boolean"
+ },
+ "baz": {
+ "examples": [
+ null
+ ],
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "foo": {
+ "examples": [
+ 8,
+ null
+ ],
+ "type": "integer",
+ "format": "int32"
+ }
+ }
+}

schemars_derive/src/attr/mod.rs

@@ -16,7 +16,7 @@ pub struct Attrs {
  pub title: Option<String>,
  pub description: Option<String>,
  pub deprecated: bool,
- // TODO pub example: Option<syn::Path>,
+ pub examples: Vec<syn::Path>,
 }
 
 #[derive(Debug)]
@@ -111,6 +111,12 @@ impl Attrs {
  }
  }
 
+ Meta(NameValue(m)) if m.path.is_ident("example") => {
+ if let Ok(fun) = parse_lit_into_path(errors, attr_type, "example", &m.lit) {
+ self.examples.push(fun)
+ }
+ }
+
  Meta(_meta_item) => {
  // TODO uncomment this for 0.8.0 (breaking change)
  // https://github.com/GREsau/schemars/issues/18

schemars_derive/src/metadata.rs

@@ -3,13 +3,14 @@ use attr::Attrs;
 use proc_macro2::{Ident, Span, TokenStream};
 use quote::{ToTokens, TokenStreamExt};
 
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct SchemaMetadata<'a> {
  pub title: Option<&'a str>,
  pub description: Option<&'a str>,
  pub deprecated: bool,
  pub read_only: bool,
  pub write_only: bool,
+ pub examples: &'a [syn::Path],
  pub default: Option<TokenStream>,
 }
 
@@ -36,7 +37,10 @@ impl<'a> SchemaMetadata<'a> {
  title: attrs.title.as_ref().and_then(none_if_empty),
  description: attrs.description.as_ref().and_then(none_if_empty),
  deprecated: attrs.deprecated,
- ..Default::default()
+ examples: &attrs.examples,
+ read_only: false,
+ write_only: false,
+ default: None,
  }
  }
 
@@ -80,6 +84,17 @@ impl<'a> SchemaMetadata<'a> {
  });
  }
 
+ if !self.examples.is_empty() {
+ let examples = self.examples.iter().map(|eg| {
+ quote! {
+ schemars::_serde_json::value::to_value(#eg())
+ }
+ });
+ setters.push(quote! {
+ metadata.examples = vec![#(#examples),*].into_iter().flatten().collect();
+ });
+ }
+
  if let Some(default) = &self.default {
  setters.push(quote! {
  metadata.default = #default.and_then(|d| schemars::_serde_json::value::to_value(d).ok());