@@ -159,32 +159,61 @@ import Data.Swagger.Internal
159159-- $lens
160160--
161161-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
162−-- to modify this structure. In combination with @'Monoid'@ instances, lenses
163−-- also make it fairly simple to construct/modify any part of the specification:
162+-- to work comfortly with it. In combination with @'Monoid'@ instances, lenses
163+-- make it fairly simple to construct/modify any part of the specification:
164164--
165165-- >>> :{
166−-- encode $ (mempty :: Swagger) & paths .~
167−-- [ ("/user", mempty & get ?~ (mempty
168−-- & produces ?~ MimeList ["application/json"]
169−-- & at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "#/definitions/User")))) ]
166+-- encode $ (mempty :: Swagger)
167+-- & definitions .~ [ ("User", mempty & type_ .~ SwaggerString) ]
168+-- & paths .~
169+-- [ ("/user", mempty & get ?~ (mempty
170+-- & produces ?~ MimeList ["application/json"]
171+-- & at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "User")))) ]
170172-- :}
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\"]}}}}"
172174--
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@
174176-- 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.
176178--
177−-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
178−-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
179−-- and allow them to be used by any type that has a @'ParamSchema'@:
179+-- For convenience, @swagger2@ uses /classy field lenses/. It means that
180+-- field accessor names can be overloaded for different types. One such
181+-- common field is @'description'@. Many components of Swagger specification
182+-- can have descriptions, and you can use the same name for them:
180183--
184+-- >>> encode $ (mempty :: Response) & description .~ "No content"
185+-- "{\"description\":\"No content\"}"
181186-- >>> :{
182187-- encode $ (mempty :: Schema)
183−-- & title ?~ "Email"
184−-- & type_ .~ SwaggerString
185−-- & format ?~ "email"
188+-- & type_ .~ SwaggerBoolean
189+-- & description ?~ "To be or not to be"
186190-- :}
187−-- "{\"format\":\"email\",\"title\":\"Email\",\"type\":\"string\"}"
191+-- "{\"type\":\"boolean\",\"description\":\"To be or not to be\"}"
192+--
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'@:
196+--
197+-- >>> encode $ (mempty :: Header) & type_ .~ SwaggerNumber
198+-- "{\"type\":\"number\"}"
199+--
200+-- Additionally, to simplify working with @'Response'@, both @'Operation'@ and @'Responses'@
201+-- have direct access to it via @'at' code@. Example:
202+--
203+-- >>> :{
204+-- encode $ (mempty :: Operation)
205+-- & at 404 ?~ Inline (mempty & description .~ "Not found")
206+-- :}
207+-- "{\"responses\":{\"404\":{\"description\":\"Not found\"}}}"
208+--
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:
213+--
214+-- - @'in_'@, @'type_'@, @'default_'@ (as keywords);
215+-- - @'maximum_'@ and @'minimum_'@ (as conflicting with @Prelude@);
216+-- - @'enum_'@ (as conflicting with @Control.Lens@).
188217
189218-- $schema
190219--
@@ -197,8 +226,8 @@ import Data.Swagger.Internal
197226-- with properties in addition to what @'ParamSchema'@ provides.
198227--
199228-- 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
201−-- this library provides two classes for schema encoding.
229+-- define a corresponding schema. To facilitate this use case
230+-- @swagger2@ provides two classes for schema encoding.
202231-- Both these classes provide means to encode /types/ as Swagger /schemas/.
203232--
204233-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,