git.iko.soy/typeable/openapi3
on 6e41dbb help sign in
typeable/openapi3/src/Data/Swagger.hs
231 lines 7.5 kB history raw
1-- |
2-- Swagger™ is a project used to describe and document RESTful APIs.
3--
4-- The Swagger specification defines a set of files required to describe such an API.
5-- These files can then be used by the Swagger-UI project to display the API
6-- and Swagger-Codegen to generate clients in various languages.
7-- Additional utilities can also take advantage of the resulting files, such as testing tools.
8module Data.Swagger (
9 -- * How to use this library
10 -- $howto
12 -- ** @'Monoid'@ instances
13 -- $monoids
15 -- ** Lenses and prisms
16 -- $lens
18 -- ** Schema specification
19 -- $schema
21 -- * Re-exports
22 module Data.Swagger.Lens,
23 module Data.Swagger.ParamSchema,
24 module Data.Swagger.Schema,
26 -- * Swagger specification
27 Swagger(..),
28 Host(..),
29 Scheme(..),
31 -- ** Info types
32 Info(..),
33 Contact(..),
34 License(..),
36 -- ** PathItem
37 PathItem(..),
39 -- ** Operations
40 Operation(..),
41 Tag(..),
42 TagName,
44 -- ** Types and formats
45 SwaggerType(..),
46 Format,
47 Definitions,
48 CollectionFormat(..),
50 -- ** Parameters
51 Param(..),
52 ParamAnySchema(..),
53 ParamOtherSchema(..),
54 ParamLocation(..),
55 ParamName,
56 Header(..),
57 HeaderName,
58 Example(..),
60 -- ** Schemas
61 ParamSchema(..),
62 Schema(..),
63 NamedSchema(..),
64 SwaggerItems(..),
65 Xml(..),
67 -- ** Responses
68 Responses(..),
69 Response(..),
70 HttpStatusCode,
72 -- ** Security
73 SecurityScheme(..),
74 SecuritySchemeType(..),
75 SecurityRequirement(..),
77 -- *** API key
78 ApiKeyParams(..),
79 ApiKeyLocation(..),
81 -- *** OAuth2
82 OAuth2Params(..),
83 OAuth2Flow(..),
84 AuthorizationURL,
85 TokenURL,
87 -- ** External documentation
88 ExternalDocs(..),
90 -- ** References
91 Reference(..),
92 Referenced(..),
94 -- ** Miscellaneous
95 MimeList(..),
96 URL(..),
97) where
99import Data.Swagger.Lens
100import Data.Swagger.ParamSchema
101import Data.Swagger.Schema
103import Data.Swagger.Internal
105-- $setup
106-- >>> import Control.Lens
107-- >>> import Data.Aeson
108-- >>> import Data.Monoid
109-- >>> import Data.Proxy
110-- >>> import GHC.Generics
111-- >>> :set -XDeriveGeneric
112-- >>> :set -XOverloadedStrings
113-- >>> :set -XOverloadedLists
114-- >>> :set -fno-warn-missing-methods
116-- $howto
117--
118-- This section explains how to use this library to work with Swagger specification.
120-- $monoids
121--
122-- Virtually all types representing Swagger specification have @'Monoid'@ instances.
123-- The @'Monoid'@ type class provides two methods — @'mempty'@ and @'mappend'@.
124--
125-- In this library you can use @'mempty'@ for a default/empty value. For instance:
126--
127-- >>> encode (mempty :: Swagger)
128-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"}}"
129--
130-- As you can see some spec properties (e.g. @"version"@) are there even when the spec is empty.
131-- That is because these properties are actually required ones.
132--
133-- You /should/ always override the default (empty) value for these properties,
134-- although it is not strictly necessary:
135--
136-- >>> encode mempty { _infoTitle = "Todo API", _infoVersion = "1.0" }
137-- "{\"version\":\"1.0\",\"title\":\"Todo API\"}"
138--
139-- You can merge two values using @'mappend'@ or its infix version @('<>')@:
140--
141-- >>> encode $ mempty { _infoTitle = "Todo API" } <> mempty { _infoVersion = "1.0" }
142-- "{\"version\":\"1.0\",\"title\":\"Todo API\"}"
143--
144-- This can be useful for combining specifications of endpoints into a whole API specification:
145--
146-- @
147-- \-\- /account subAPI specification
148-- accountAPI :: Swagger
149--
150-- \-\- /task subAPI specification
151-- taskAPI :: Swagger
152--
153-- \-\- while API specification is just a combination
154-- \-\- of subAPIs' specifications
155-- api :: Swagger
156-- api = accountAPI <> taskAPI
157-- @
159-- $lens
160--
161-- 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:
164--
165-- >>> :{
166-- encode $ (mempty :: Swagger) & paths .~
167-- [ ("/user", mempty & get ?~ (mempty
168-- & produces ?~ MimeList ["application/json"]
169-- & responses .~ (mempty
170-- & responses . at 200 ?~ Inline (mempty & schema ?~ Ref (Reference "#/definitions/User")))))]
171-- :}
172-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/#/definitions/User\"},\"description\":\"\"}},\"produces\":[\"application/json\"]}}}}"
173--
174-- In the snippet above we declare API paths with a single path @/user@ providing method @GET@
175-- which produces @application/json@ output and should respond with code @200@ and body specified
176-- by schema @User@ (which should be defined in @definitions@ property of swagger specification).
177--
178-- Since @'ParamSchema'@ is basically the /base schema specification/, a special
179-- @'HasParamSchema'@ class has been introduced to generalize @'ParamSchema'@ lenses
180-- and allow them to be used by any type that has a @'ParamSchema'@:
181--
182-- >>> :{
183-- encode $ (mempty :: Schema)
184-- & title ?~ "Email"
185-- & type_ .~ SwaggerString
186-- & format ?~ "email"
187-- :}
188-- "{\"format\":\"email\",\"title\":\"Email\",\"type\":\"string\"}"
190-- $schema
191--
192-- @'ParamSchema'@ and @'Schema'@ are the two core types for data model specification.
193--
194-- @'ParamSchema' t@ specifies all the common properties, available for every data schema.
195-- The @t@ parameter imposes some restrictions on @type@ and @items@ properties (see @'SwaggerType'@ and @'SwaggerItems'@).
196--
197-- @'Schema'@ is used for request and response bodies and allows specifying objects
198-- with properties in addition to what @'ParamSchema'@ provides.
199--
200-- In most cases you will have a Haskell data type for which you would like to
201-- define a corresponding schema. To facilitate thise use case
202-- this library provides two classes for schema encoding.
203-- Both these classes provide means to encode /types/ as Swagger /schemas/.
204--
205-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
206-- such as query parameters, headers and URL path pieces.
207-- Its corresponding value-encoding class is @'ToHttpApiData'@ (from @http-api-data@ package).
208--
209-- @'ToSchema'@ is used for request and response bodies and mostly differ from
210-- primitive parameters by allowing objects/mappings in addition to primitive types and arrays.
211-- Its corresponding value-encoding class is @'ToJSON'@ (from @aeson@ package).
212--
213-- While lenses and prisms make it easy to define schemas, it might be that you don't need to:
214-- @'ToSchema'@ and @'ToParamSchema'@ classes both have default @'Generic'@-based implementations!
215--
216-- @'ToSchema'@ default implementation is also aligned with @'ToJSON'@ default implementation with
217-- the only difference being for sum encoding. @'ToJSON'@ defaults sum encoding to @'defaultTaggedObject'@,
218-- while @'ToSchema'@ defaults to something which corresponds to @'ObjectWithSingleField'@. This is due to
219-- @'defaultTaggedObject'@ behavior being hard to specify in Swagger.
220--
221-- Here's an example showing @'ToJSON'@–@'ToSchema'@ correspondance:
222--
223-- >>> data Person = Person { name :: String, age :: Integer } deriving Generic
224-- >>> instance ToJSON Person
225-- >>> instance ToSchema Person
226-- >>> encode (Person "David" 28)
227-- "{\"age\":28,\"name\":\"David\"}"
228-- >>> encode $ toSchema (Proxy :: Proxy Person)
229-- "{\"required\":[\"name\",\"age\"],\"type\":\"object\",\"properties\":{\"age\":{\"type\":\"integer\"},\"name\":{\"type\":\"string\"}}}"
230--