@@ -159,32 +159,61 @@ import Data.Swagger.Internal
161-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
161-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
162−-- to modify this structure. In combination with @'Monoid'@ instances, lenses
162+-- to work comfortly with it. In combination with @'Monoid'@ instances, lenses
163−-- also make it fairly simple to construct/modify any part of the specification:
163+-- make it fairly simple to construct/modify any part of the specification:
166−-- encode $ (mempty :: Swagger) & paths .~
166+-- encode $ (mempty :: Swagger)
167+-- & definitions .~ [ ("User", mempty & type_ .~ SwaggerString) ]
167−-- [ ("/user", mempty & get ?~ (mempty
169+-- [ ("/user", mempty & get ?~ (mempty
168−-- & produces ?~ MimeList ["application/json"]
170+-- & produces ?~ MimeList ["application/json"]
169−-- & at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "#/definitions/User")))) ]
171+-- & at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "User")))) ]
171−-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}}"
173+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"User\":{\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}}"
173−-- In the snippet above we declare API paths with a single path @/user@ providing method @GET@
175+-- In the snippet above we declare API with a single path @/user@ providing method @GET@
174-- which produces @application/json@ output and should respond with code @200@ and body specified
176-- which produces @application/json@ output and should respond with code @200@ and body specified
175−-- by schema @User@ (which should be defined in @definitions@ property of swagger specification).
177+-- by schema @User@ which is defined in @'definitions'@ property of swagger specification.
177−-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
179+-- For convenience, @swagger2@ uses /classy field lenses/. It means that
178−-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
180+-- field accessor names can be overloaded for different types. One such
179−-- and allow them to be used by any type that has a @'ParamSchema'@:
181+-- common field is @'description'@. Many components of Swagger specification
182+-- can have descriptions, and you can use the same name for them:
184+-- >>> encode $ (mempty :: Response) & description .~ "No content"
185+-- "{\"description\":\"No content\"}"
182-- encode $ (mempty :: Schema)
187-- encode $ (mempty :: Schema)
183−-- & title ?~ "Email"
188+-- & type_ .~ SwaggerBoolean
184−-- & type_ .~ SwaggerString
189+-- & description ?~ "To be or not to be"
185−-- & format ?~ "email"
187−-- "{\"format\":\"email\",\"title\":\"Email\",\"type\":\"string\"}"
191+-- "{\"type\":\"boolean\",\"description\":\"To be or not to be\"}"
193+-- @'ParamSchema'@ is basically the /base schema specification/ and many types contain it (see @'HasParamSchema'@).
194+-- So for convenience, all @'ParamSchema'@ fields are transitively made fields of the type that has it.
195+-- For example, you can use @'type_'@ to access @'SwaggerType'@ of @'Header'@ schema without having to use @'paramSchema'@:
197+-- >>> encode $ (mempty :: Header) & type_ .~ SwaggerNumber
198+-- "{\"type\":\"number\"}"
200+-- Additionally, to simplify working with @'Response'@, both @'Operation'@ and @'Responses'@
201+-- have direct access to it via @'at' code@. Example:
204+-- encode $ (mempty :: Operation)
205+-- & at 404 ?~ Inline (mempty & description .~ "Not found")
207+-- "{\"responses\":{\"404\":{\"description\":\"Not found\"}}}"
209+-- You might've noticed that @'type_'@ has an extra underscore in its name
210+-- compared to, say, @'description'@ field accessor.
211+-- This is because @type@ is a keyword in Haskell.
212+-- A few other field accessors are modified in this way:
214+-- - @'in_'@, @'type_'@, @'default_'@ (as keywords);
215+-- - @'maximum_'@ and @'minimum_'@ (as conflicting with @Prelude@);
216+-- - @'enum_'@ (as conflicting with @Control.Lens@).
189-- $schema
218-- $schema
@@ -197,8 +226,8 @@ import Data.Swagger.Internal
197-- with properties in addition to what @'ParamSchema'@ provides.
226-- with properties in addition to what @'ParamSchema'@ provides.
199-- In most cases you will have a Haskell data type for which you would like to
228-- In most cases you will have a Haskell data type for which you would like to
200−-- define a corresponding schema. To facilitate thise use case
229+-- define a corresponding schema. To facilitate this use case
201−-- this library provides two classes for schema encoding.
230+-- @swagger2@ provides two classes for schema encoding.
202-- Both these classes provide means to encode /types/ as Swagger /schemas/.
231-- Both these classes provide means to encode /types/ as Swagger /schemas/.
204-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
233-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,