@@ -168,6 +168,10 @@ import Data.Swagger.Internal
169-- "{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}"
169-- "{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}"
171+-- In the snippet above we declare API paths with a single path @/user@ providing method @GET@
172+-- which produces @application/json@ output and should respond with code @200@ and body specified
173+-- by schema @User@ (which should be defined in @definitions@ property of swagger specification).
171-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
175-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
172-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
176-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
173-- and allow them to be used by any type that has a @'ParamSchema'@:
177-- and allow them to be used by any type that has a @'ParamSchema'@:
@@ -182,8 +186,18 @@ import Data.Swagger.Internal
183-- $schema
187-- $schema
189+-- @'ParamSchema'@ and @'Schema'@ are the two core types for data model specification.
191+-- @'ParamSchema' t@ specifies all the common properties, available for every data schema.
192+-- The @t@ parameter imposes some restrictions on @type@ and @items@ properties (see @'SwaggerType'@ and @'SwaggerItems'@).
194+-- @'Schema'@ is used for request and response bodies and allows specifying objects
195+-- with properties in addition to what @'ParamSchema'@ provides.
197+-- In most cases you will have a Haskell data type for which you would like to
198+-- define a corresponding schema. To facilitate thise use case
185−-- This library provides two classes for schema encoding.
199+-- this library provides two classes for schema encoding.
186−-- Both these classes provide means to encode _types_ as Swagger _schemas_.
200+-- Both these classes provide means to encode /types/ as Swagger /schemas/.
188-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
202-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
189-- such as query parameters, headers and URL path pieces.
203-- such as query parameters, headers and URL path pieces.