@@ -123,19 +123,43 @@ declareSchema :: ToSchema a => proxy a -> Declare Definitions Schema
123123declareSchema = fmap snd . declareNamedSchema
124124
125125-- | Convert a type into an optionally named schema.
126+--
127+-- >>> encode <$> toNamedSchema (Proxy :: Proxy String)
128+-- (Nothing,"{\"type\":\"string\"}")
129+--
130+-- >>> encode <$> toNamedSchema (Proxy :: Proxy Day)
131+-- (Just "Day","{\"format\":\"yyyy-mm-dd\",\"type\":\"string\"}")
126132toNamedSchema :: ToSchema a => proxy a -> NamedSchema
127133toNamedSchema = undeclare . declareNamedSchema
128134
129135-- | Get type's schema name according to its @'ToSchema'@ instance.
136+--
137+-- >>> schemaName (Proxy :: Proxy Int)
138+-- Nothing
139+--
140+-- >>> schemaName (Proxy :: Proxy UTCTime)
141+-- Just "UTCTime"
130142schemaName :: ToSchema a => proxy a -> Maybe T.Text
131143schemaName = fst . toNamedSchema
132144
133145-- | Convert a type into a schema.
146+--
147+-- >>> encode $ toSchema (Proxy :: Proxy Int8)
148+-- "{\"maximum\":127,\"minimum\":-128,\"type\":\"integer\"}"
149+--
150+-- >>> encode $ toSchema (Proxy :: Proxy [Day])
151+-- "{\"items\":{\"$ref\":\"#/definitions/Day\"},\"type\":\"array\"}"
134152toSchema :: ToSchema a => proxy a -> Schema
135153toSchema = snd . toNamedSchema
136154
137155-- | Convert a type into a referenced schema if possible.
138156-- Only named schemas can be referenced, nameless schemas are inlined.
157+--
158+-- >>> encode $ toSchemaRef (Proxy :: Proxy Integer)
159+-- "{\"type\":\"integer\"}"
160+--
161+-- >>> encode $ toSchemaRef (Proxy :: Proxy Day)
162+-- "{\"$ref\":\"#/definitions/Day\"}"
139163toSchemaRef :: ToSchema a => proxy a -> Referenced Schema
140164toSchemaRef = undeclare . declareSchemaRef
141165
@@ -203,6 +227,9 @@ inlineAllSchemas = inlineSchemasWhen (const True)
203227
204228-- | Convert a type into a schema without references.
205229--
230+-- >>> encode $ toInlinedSchema (Proxy :: Proxy [Day])
231+-- "{\"items\":{\"format\":\"yyyy-mm-dd\",\"type\":\"string\"},\"type\":\"array\"}"
232+--
206233-- __WARNING:__ @'toInlinedSchema'@ will produce infinite schema
207234-- when inlining recursive schemas.
208235toInlinedSchema :: ToSchema a => proxy a -> Schema