@@ -18,10 +18,18 @@ module Data.Swagger (
1818 -- ** Schema specification
1919 -- $schema
2020
21+ -- ** Manipulation
22+ -- $manipulation
23+
24+ -- ** Validation
25+ -- $validation
26+
2127 -- * Re-exports
2228 module Data.Swagger.Lens,
29+ module Data.Swagger.Operation,
2330 module Data.Swagger.ParamSchema,
2431 module Data.Swagger.Schema,
32+ module Data.Swagger.Schema.Validation,
2533
2634 -- * Swagger specification
2735 Swagger(..),
@@ -97,8 +105,10 @@ module Data.Swagger (
97105) where
98106
99107import Data.Swagger.Lens
108+import Data.Swagger.Operation
100109import Data.Swagger.ParamSchema
101110import Data.Swagger.Schema
111+import Data.Swagger.Schema.Validation
102112
103113import Data.Swagger.Internal
104114
@@ -214,7 +224,7 @@ import Data.Swagger.Internal
214224-- A few other field accessors are modified in this way:
215225--
216226-- - @'in_'@, @'type_'@, @'default_'@ (as keywords);
217−-- - @'maximum_'@ and @'minimum_'@ (as conflicting with @Prelude@);
227+-- - @'maximum_'@, @'minimum_'@, @'head_'@ (as conflicting with @Prelude@);
218228-- - @'enum_'@ (as conflicting with @Control.Lens@).
219229
220230-- $schema
@@ -257,5 +267,17 @@ import Data.Swagger.Internal
257267-- "{\"age\":28,\"name\":\"David\"}"
258268-- >>> encode $ toSchema (Proxy :: Proxy Person)
259269-- "{\"required\":[\"name\",\"age\"],\"type\":\"object\",\"properties\":{\"age\":{\"type\":\"integer\"},\"name\":{\"type\":\"string\"}}}"
270+
271+-- $manipulation
272+-- Sometimes you have to work with an imported or generated @'Swagger'@.
273+-- For instance, <servant-swagger http://hackage.haskell.org/package/servant-swagger> generates basic @'Swagger'@
274+-- for a type-level servant API.
260275--
276+-- Lenses and prisms can be used to manipulate such specification to add additional information, tags, extra responses, etc.
277+-- To facilitate common needs, @'Data.Swagger.Operation'@ module provides useful helpers.
261278
279+-- $validation
280+-- While @'ToParamSchema'@ and @'ToSchema'@ provide means to easily obtain schemas for Haskell types,
281+-- there is no static mechanism to ensure those instances correspond to the @'ToHttpApiData'@ or @'ToJSON'@ instances.
282+--
283+-- @'Data.Swagger.Schema.Validation'@ addresses @'ToJSON'@/@'ToSchema'@ validation.