@@ -159,7 +159,7 @@ 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 work comfortly with it. In combination with @'Monoid'@ instances, lenses
162+-- to work comfortably with it. In combination with @'Monoid'@ instances, lenses
163-- 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:
@@ -173,13 +173,14 @@ import Data.Swagger.Internal
174-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"User\":{\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"404\":{\"description\":\"User info not found\"},\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"OK\"}},\"produces\":[\"application/json\"]}}}}"
174-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"User\":{\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"404\":{\"description\":\"User info not found\"},\"200\":{\"schema\":{\"$ref\":\"#/definitions/User\"},\"description\":\"OK\"}},\"produces\":[\"application/json\"]}}}}"
176−-- In the snippet above we declare API with a single path @/user@ providing method @GET@
176+-- In the snippet above we declare an API with a single path @/user@. This path provides method @GET@
177−-- which produces @application/json@ output and should respond with code @200@ and body specified
177+-- which produces @application/json@ output. It should respond with code @200@ and body specified
178-- by schema @User@ which is defined in @'definitions'@ property of swagger specification.
178-- by schema @User@ which is defined in @'definitions'@ property of swagger specification.
179+-- Alternatively it may respond with code @404@ meaning that user info is not found.
180-- For convenience, @swagger2@ uses /classy field lenses/. It means that
181-- For convenience, @swagger2@ uses /classy field lenses/. It means that
181-- field accessor names can be overloaded for different types. One such
182-- field accessor names can be overloaded for different types. One such
182−-- common field is @'description'@. Many components of Swagger specification
183+-- common field is @'description'@. Many components of a Swagger specification
183-- can have descriptions, and you can use the same name for them:
184-- can have descriptions, and you can use the same name for them:
185-- >>> encode $ (mempty :: Response) & description .~ "No content"
186-- >>> encode $ (mempty :: Response) & description .~ "No content"