@@ -6,6 +6,19 @@
66-- and Swagger-Codegen to generate clients in various languages.
77-- Additional utilities can also take advantage of the resulting files, such as testing tools.
88module Data.Swagger (
9+ -- * How to use this library
10+ -- $howto
11+
12+ -- ** @'Monoid'@ instances
13+ -- $monoids
14+
15+ -- ** Lenses and prisms
16+ -- $lens
17+
18+ -- ** Schema specification
19+ -- $schema
20+
21+ -- * Re-exports
922 module Data.Swagger.ParamSchema,
1023 module Data.Swagger.Schema,
1124
@@ -14,25 +27,25 @@ module Data.Swagger (
1427 Host(..),
1528 Scheme(..),
1629
17− -- * Info types
30+ -- ** Info types
1831 Info(..),
1932 Contact(..),
2033 License(..),
2134
22− -- * Paths
35+ -- ** Paths
2336 Paths(..),
2437 PathItem(..),
2538
26− -- * Operations
39+ -- ** Operations
2740 Tag(..),
2841 Operation(..),
2942
30− -- * Types and formats
43+ -- ** Types and formats
3144 SwaggerType(..),
3245 Format,
3346 CollectionFormat(..),
3447
35− -- * Parameters
48+ -- ** Parameters
3649 Param(..),
3750 ParamAnySchema(..),
3851 ParamOtherSchema(..),
@@ -42,39 +55,39 @@ module Data.Swagger (
4255 Header(..),
4356 Example(..),
4457
45− -- * Schemas
58+ -- ** Schemas
4659 ParamSchema(..),
4760 Schema(..),
4861 SwaggerItems(..),
4962 Xml(..),
5063
51− -- * Responses
64+ -- ** Responses
5265 Responses(..),
5366 Response(..),
5467
55− -- * Security
68+ -- ** Security
5669 SecurityScheme(..),
5770 SecuritySchemeType(..),
5871 SecurityRequirement(..),
5972
60− -- ** API key
73+ -- *** API key
6174 ApiKeyParams(..),
6275 ApiKeyLocation(..),
6376
64− -- ** OAuth2
77+ -- *** OAuth2
6578 OAuth2Params(..),
6679 OAuth2Flow(..),
6780 AuthorizationURL,
6881 TokenURL,
6982
70− -- * External documentation
83+ -- ** External documentation
7184 ExternalDocs(..),
7285
73− -- * References
86+ -- ** References
7487 Reference(..),
7588 Referenced(..),
7689
77− -- * Miscellaneous
90+ -- ** Miscellaneous
7891 MimeList(..),
7992 URL(..),
8093) where
@@ -84,3 +97,116 @@ import Data.Swagger.Schema
8497
8598import Data.Swagger.Internal
8699
100+-- $setup
101+-- >>> import Control.Lens
102+-- >>> import Data.Aeson
103+-- >>> import Data.Monoid
104+-- >>> import Data.Proxy
105+-- >>> import Data.Swagger.Lens
106+-- >>> import GHC.Generics
107+-- >>> :set -XDeriveGeneric
108+-- >>> :set -XOverloadedStrings
109+-- >>> :set -XOverloadedLists
110+
111+-- $howto
112+--
113+-- This section explains how to use this library to work with Swagger specification.
114+
115+-- $monoids
116+--
117+-- Virtually all types representing Swagger specification have @'Monoid'@ instances.
118+-- The @'Monoid'@ type class provides two methods — @'mempty'@ and @'mappend'@.
119+--
120+-- In this library you can use @'mempty'@ for a default/empty value. For instance:
121+--
122+-- >>> encode (mempty :: Swagger)
123+-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"}}"
124+--
125+-- As you can see some spec properties (e.g. @"version"@) are there even when the spec is empty.
126+-- That is because these properties are actually required ones.
127+--
128+-- You /should/ always override the default (empty) value for these properties,
129+-- although it is not strictly necessary:
130+--
131+-- >>> encode mempty { _infoTitle = "Todo API", _infoVersion = "1.0" }
132+-- "{\"version\":\"1.0\",\"title\":\"Todo API\"}"
133+--
134+-- You can merge two values using @'mappend'@ or its infix version @('<>')@:
135+--
136+-- >>> encode $ mempty { _infoTitle = "Todo API" } <> mempty { _infoVersion = "1.0" }
137+-- "{\"version\":\"1.0\",\"title\":\"Todo API\"}"
138+--
139+-- This can be useful for combining specifications of endpoints into a whole API specification:
140+--
141+-- @
142+-- \-\- /account subAPI specification
143+-- accountAPI :: Swagger
144+--
145+-- \-\- /task subAPI specification
146+-- taskAPI :: Swagger
147+--
148+-- \-\- while API specification is just a combination
149+-- \-\- of subAPIs' specifications
150+-- api :: Swagger
151+-- api = accountAPI <> taskAPI
152+-- @
153+
154+-- $lens
155+--
156+-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
157+-- to modify this structure. In combination with @'Monoid'@ instances, lenses
158+-- also make it fairly simple to construct/modify any part of the specification:
159+--
160+-- >>> :{
161+-- encode $ mempty & pathsMap .~
162+-- [ ("/user", mempty & pathItemGet ?~ (mempty
163+-- & operationProduces ?~ MimeList ["application/json"]
164+-- & operationResponses .~ (mempty
165+-- & responsesResponses . at 200 ?~ Inline (mempty & responseSchema ?~ Ref (Reference "#/definitions/User")))))]
166+-- :}
167+-- "{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}"
168+--
169+-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
170+-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
171+-- and allow them to be used by any type that has a @'ParamSchema'@:
172+--
173+-- >>> :{
174+-- encode $ mempty
175+-- & schemaTitle ?~ "Email"
176+-- & schemaType .~ SwaggerString
177+-- & schemaFormat ?~ "email"
178+-- :}
179+-- "{\"format\":\"email\",\"title\":\"Email\",\"type\":\"string\"}"
180+
181+-- $schema
182+--
183+-- This library provides two classes for schema encoding.
184+-- Both these classes provide means to encode _types_ as Swagger _schemas_.
185+--
186+-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
187+-- such as query parameters, headers and URL path pieces.
188+-- Its corresponding value-encoding class is @'ToHttpApiData'@ (from @http-api-data@ package).
189+--
190+-- @'ToSchema'@ is used for request and response bodies and mostly differ from
191+-- primitive parameters by allowing objects/mappings in addition to primitive types and arrays.
192+-- Its corresponding value-encoding class is @'ToJSON'@ (from @aeson@ package).
193+--
194+-- While lenses and prisms make it easy to define schemas, it might be that you don't need to:
195+-- @'ToSchema'@ and @'ToParamSchema'@ classes both have default @'Generic'@-based implementations!
196+--
197+-- @'ToSchema'@ default implementation is also aligned with @'ToJSON'@ default implementation with
198+-- the only difference being for sum encoding. @'ToJSON'@ defaults sum encoding to @'defaultTaggedObject'@,
199+-- while @'ToSchema'@ defaults to something which corresponds to @'ObjectWithSingleField'@. This is due to
200+-- @'defaultTaggedObject'@ behavior being hard to specify in Swagger.
201+--
202+-- Here's an example showing @'ToJSON'@–@'ToSchema'@ correspondance:
203+--
204+-- >>> data Person = Person { name :: String, age :: Integer } deriving Generic
205+-- >>> instance ToJSON Person
206+-- >>> instance ToSchema Person
207+-- >>> encode (Person "David" 28)
208+-- "{\"age\":28,\"name\":\"David\"}"
209+-- >>> encode $ toSchema (Proxy :: Proxy Person)
210+-- "{\"required\":[\"name\",\"age\"],\"type\":\"object\",\"properties\":{\"age\":{\"type\":\"integer\"},\"name\":{\"type\":\"string\"}}}"
211+--
212+