git.iko.soy/typeable/openapi3
on master help sign in
typeable/openapi3/src/Data/OpenApi.hs
428 lines 13 kB history raw
1-- |
2-- Module: Data.OpenApi
3-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
4-- Stability: experimental
5--
6-- Swagger™ is a project used to describe and document RESTful APIs.
7--
8-- The Swagger specification defines a set of files required to describe such an API.
9-- These files can then be used by the Swagger-UI project to display the API
10-- and Swagger-Codegen to generate clients in various languages.
11-- Additional utilities can also take advantage of the resulting files, such as testing tools.
12module Data.OpenApi (
13 -- * How to use this library
14 -- $howto
16 -- ** @'Monoid'@ instances
17 -- $monoids
19 -- ** Lenses and prisms
20 -- $lens
22 -- ** Schema specification
23 -- $schema
25 -- ** Manipulation
26 -- $manipulation
28 -- ** Validation
29 -- $validation
31 -- * Re-exports
32 module Data.OpenApi.Lens,
33 module Data.OpenApi.Optics,
34 module Data.OpenApi.Operation,
35 module Data.OpenApi.ParamSchema,
36 module Data.OpenApi.Schema,
37 module Data.OpenApi.Schema.Validation,
39 -- * Swagger specification
40 OpenApi(..),
41 Server(..),
42 ServerVariable(..),
43 Components(..),
45 -- ** Info types
46 Info(..),
47 Contact(..),
48 License(..),
50 -- ** PathItem
51 PathItem(..),
53 -- ** Operations
54 Operation(..),
55 Tag(..),
56 TagName,
58 -- ** Types and formats
59 OpenApiType(..),
60 Format,
61 Definitions,
62 Style(..),
64 -- ** Parameters
65 Param(..),
66 ParamLocation(..),
67 ParamName,
68 Header(..),
69 HeaderName,
70 Example(..),
71 RequestBody(..),
72 MediaTypeObject(..),
73 Encoding(..),
75 -- ** Schemas
76 Schema(..),
77 NamedSchema(..),
78 OpenApiItems(..),
79 Xml(..),
80 Pattern,
81 AdditionalProperties(..),
82 Discriminator(..),
84 -- ** Responses
85 Responses(..),
86 Response(..),
87 HttpStatusCode,
88 Link(..),
89 Callback(..),
91 -- ** Security
92 SecurityScheme(..),
93 SecuritySchemeType(..),
94 HttpSchemeType(..),
95 SecurityDefinitions(..),
96 SecurityRequirement(..),
98 -- *** API key
99 ApiKeyParams(..),
100 ApiKeyLocation(..),
102 -- *** OAuth2
103 OAuth2Flows(..),
104 OAuth2Flow(..),
105 OAuth2ImplicitFlow(..),
106 OAuth2PasswordFlow(..),
107 OAuth2ClientCredentialsFlow(..),
108 OAuth2AuthorizationCodeFlow(..),
109 AuthorizationURL,
110 TokenURL,
112 -- ** External documentation
113 ExternalDocs(..),
115 -- ** References
116 Reference(..),
117 Referenced(..),
119 -- ** Miscellaneous
120 MimeList(..),
121 URL(..),
122) where
124import Data.OpenApi.Lens
125import Data.OpenApi.Optics ()
126import Data.OpenApi.Operation
127import Data.OpenApi.ParamSchema
128import Data.OpenApi.Schema
129import Data.OpenApi.Schema.Validation
131import Data.OpenApi.Internal
133-- $setup
134-- >>> import Control.Lens
135-- >>> import Data.Aeson
136-- >>> import Data.Monoid
137-- >>> import Data.Proxy
138-- >>> import GHC.Generics
139-- >>> import qualified Data.ByteString.Lazy.Char8 as BSL
140-- >>> import Data.OpenApi.Internal.Utils
141-- >>> :set -XDeriveGeneric
142-- >>> :set -XOverloadedStrings
143-- >>> :set -XOverloadedLists
144-- >>> :set -fno-warn-missing-methods
146-- $howto
147--
148-- This section explains how to use this library to work with Swagger specification.
150-- $monoids
151--
152-- Virtually all types representing Swagger specification have @'Monoid'@ instances.
153-- The @'Monoid'@ type class provides two methods — @'mempty'@ and @'mappend'@.
154--
155-- In this library you can use @'mempty'@ for a default/empty value. For instance:
156--
157-- >>> BSL.putStrLn $ encodePretty (mempty :: OpenApi)
158-- {
159-- "components": {},
160-- "info": {
161-- "title": "",
162-- "version": ""
163-- },
164-- "openapi": "3.0.0",
165-- "paths": {}
166-- }
167--
168-- As you can see some spec properties (e.g. @"version"@) are there even when the spec is empty.
169-- That is because these properties are actually required ones.
170--
171-- You /should/ always override the default (empty) value for these properties,
172-- although it is not strictly necessary:
173--
174-- >>> BSL.putStrLn $ encodePretty mempty { _infoTitle = "Todo API", _infoVersion = "1.0" }
175-- {
176-- "title": "Todo API",
177-- "version": "1.0"
178-- }
179--
180-- You can merge two values using @'mappend'@ or its infix version @('<>')@:
181--
182-- >>> BSL.putStrLn $ encodePretty $ mempty { _infoTitle = "Todo API" } <> mempty { _infoVersion = "1.0" }
183-- {
184-- "title": "Todo API",
185-- "version": "1.0"
186-- }
188--
189-- This can be useful for combining specifications of endpoints into a whole API specification:
190--
191-- @
192-- \-\- /account subAPI specification
193-- accountAPI :: OpenApi
194--
195-- \-\- /task subAPI specification
196-- taskAPI :: OpenApi
197--
198-- \-\- while API specification is just a combination
199-- \-\- of subAPIs' specifications
200-- api :: OpenApi
201-- api = accountAPI <> taskAPI
202-- @
204-- $lens
205--
206-- Note: if you're working with the <https://hackage.haskell.org/package/optics optics> library, take a look at "Data.OpenApi.Optics".
207--
208-- Since @'Swagger'@ has a fairly complex structure, lenses and prisms are used
209-- to work comfortably with it. In combination with @'Monoid'@ instances, lenses
210-- make it fairly simple to construct/modify any part of the specification:
211--
212-- >>> :{
213-- BSL.putStrLn $ encodePretty $ (mempty :: OpenApi)
214-- & components . schemas .~ [ ("User", mempty & type_ ?~ OpenApiString) ]
215-- & paths .~
216-- [ ("/user", mempty & get ?~ (mempty
217-- & at 200 ?~ ("OK" & _Inline.content.at "application/json" ?~ (mempty & schema ?~ Ref (Reference "User")))
218-- & at 404 ?~ "User info not found")) ]
219-- :}
220-- {
221-- "components": {
222-- "schemas": {
223-- "User": {
224-- "type": "string"
225-- }
226-- }
227-- },
228-- "info": {
229-- "title": "",
230-- "version": ""
231-- },
232-- "openapi": "3.0.0",
233-- "paths": {
234-- "/user": {
235-- "get": {
236-- "responses": {
237-- "200": {
238-- "content": {
239-- "application/json": {
240-- "schema": {
241-- "$ref": "#/components/schemas/User"
242-- }
243-- }
244-- },
245-- "description": "OK"
246-- },
247-- "404": {
248-- "description": "User info not found"
249-- }
250-- }
251-- }
252-- }
253-- }
254-- }
255--
256-- In the snippet above we declare an API with a single path @/user@. This path provides method @GET@
257-- which produces @application/json@ output. It should respond with code @200@ and body specified
258-- by schema @User@ which is defined in @'definitions'@ property of swagger specification.
259-- Alternatively it may respond with code @404@ meaning that user info is not found.
260--
261-- For convenience, @swagger2@ uses /classy field lenses/. It means that
262-- field accessor names can be overloaded for different types. One such
263-- common field is @'description'@. Many components of a Swagger specification
264-- can have descriptions, and you can use the same name for them:
265--
266-- >>> BSL.putStrLn $ encodePretty $ (mempty :: Response) & description .~ "No content"
267-- {
268-- "description": "No content"
269-- }
270-- >>> :{
271-- BSL.putStrLn $ encodePretty $ (mempty :: Schema)
272-- & type_ ?~ OpenApiBoolean
273-- & description ?~ "To be or not to be"
274-- :}
275-- {
276-- "description": "To be or not to be",
277-- "type": "boolean"
278-- }
279--
280-- Additionally, to simplify working with @'Response'@, both @'Operation'@ and @'Responses'@
281-- have direct access to it via @'at' code@. Example:
282--
283-- >>> :{
284-- BSL.putStrLn $ encodePretty $ (mempty :: Operation)
285-- & at 404 ?~ "Not found"
286-- :}
287-- {
288-- "responses": {
289-- "404": {
290-- "description": "Not found"
291-- }
292-- }
293-- }
294--
295-- You might've noticed that @'type_'@ has an extra underscore in its name
296-- compared to, say, @'description'@ field accessor.
297-- This is because @type@ is a keyword in Haskell.
298-- A few other field accessors are modified in this way:
299--
300-- - @'in_'@, @'type_'@, @'default_'@ (as keywords);
301-- - @'maximum_'@, @'minimum_'@, @'head_'@ (as conflicting with @Prelude@);
302-- - @'enum_'@ (as conflicting with @Control.Lens@).
304-- $schema
305--
306-- @'ParamSchema'@ and @'Schema'@ are the two core types for data model specification.
307--
308-- @'ParamSchema' t@ specifies all the common properties, available for every data schema.
309-- The @t@ parameter imposes some restrictions on @type@ and @items@ properties (see @'OpenApiType'@ and @'OpenApiItems'@).
310--
311-- @'Schema'@ is used for request and response bodies and allows specifying objects
312-- with properties in addition to what @'ParamSchema'@ provides.
313--
314-- In most cases you will have a Haskell data type for which you would like to
315-- define a corresponding schema. To facilitate this use case
316-- @swagger2@ provides two classes for schema encoding.
317-- Both these classes provide means to encode /types/ as Swagger /schemas/.
318--
319-- @'ToParamSchema'@ is intended to be used for primitive API endpoint parameters,
320-- such as query parameters, headers and URL path pieces.
321-- Its corresponding value-encoding class is @'ToHttpApiData'@ (from @http-api-data@ package).
322--
323-- @'ToSchema'@ is used for request and response bodies and mostly differ from
324-- primitive parameters by allowing objects/mappings in addition to primitive types and arrays.
325-- Its corresponding value-encoding class is @'ToJSON'@ (from @aeson@ package).
326--
327-- While lenses and prisms make it easy to define schemas, it might be that you don't need to:
328-- @'ToSchema'@ and @'ToParamSchema'@ classes both have default @'Generic'@-based implementations!
329--
330-- @'ToSchema'@ default implementation is also aligned with @'ToJSON'@ default implementation with
331-- the only difference being for sum encoding. @'ToJSON'@ defaults sum encoding to @'defaultTaggedObject'@,
332-- while @'ToSchema'@ defaults to something which corresponds to @'ObjectWithSingleField'@. This is due to
333-- @'defaultTaggedObject'@ behavior being hard to specify in Swagger.
334--
335-- Here's an example showing @'ToJSON'@–@'ToSchema'@ correspondance:
336--
337-- >>> data Person = Person { name :: String, age :: Integer } deriving Generic
338-- >>> instance ToJSON Person
339-- >>> instance ToSchema Person
340-- >>> BSL.putStrLn $ encodePretty (Person "David" 28)
341-- {
342-- "age": 28,
343-- "name": "David"
344-- }
345-- >>> BSL.putStrLn $ encodePretty $ toSchema (Proxy :: Proxy Person)
346-- {
347-- "properties": {
348-- "age": {
349-- "type": "integer"
350-- },
351-- "name": {
352-- "type": "string"
353-- }
354-- },
355-- "required": [
356-- "name",
357-- "age"
358-- ],
359-- "type": "object"
360-- }
361--
362-- This package implements OpenAPI 3.0 spec, which supports @oneOf@ in schemas, allowing any sum types
363-- to be faithfully represented. All sum encodings supported by @aeson@ are supported here as well, with
364-- an exception of 'Data.Aeson.TwoElemArray', since OpenAPI spec does not support heterogeneous arrays.
365--
366-- An example with 'Data.Aeson.TaggedObject' encoding:
367--
368-- >>> data Error = ErrorNoUser { userId :: Int } | ErrorAccessDenied { requiredPermission :: String } deriving Generic
369-- >>> instance ToJSON Error
370-- >>> instance ToSchema Error
371-- >>> BSL.putStrLn $ encodePretty $ toSchema (Proxy :: Proxy Error)
372-- {
373-- "oneOf": [
374-- {
375-- "properties": {
376-- "tag": {
377-- "enum": [
378-- "ErrorNoUser"
379-- ],
380-- "type": "string"
381-- },
382-- "userId": {
383-- "maximum": 9223372036854775807,
384-- "minimum": -9223372036854775808,
385-- "type": "integer"
386-- }
387-- },
388-- "required": [
389-- "userId",
390-- "tag"
391-- ],
392-- "type": "object"
393-- },
394-- {
395-- "properties": {
396-- "requiredPermission": {
397-- "type": "string"
398-- },
399-- "tag": {
400-- "enum": [
401-- "ErrorAccessDenied"
402-- ],
403-- "type": "string"
404-- }
405-- },
406-- "required": [
407-- "requiredPermission",
408-- "tag"
409-- ],
410-- "type": "object"
411-- }
412-- ],
413-- "type": "object"
414-- }
416-- $manipulation
417-- Sometimes you have to work with an imported or generated @'Swagger'@.
418-- For instance, <servant-swagger http://hackage.haskell.org/package/servant-swagger> generates basic @'Swagger'@
419-- for a type-level servant API.
420--
421-- Lenses and prisms can be used to manipulate such specification to add additional information, tags, extra responses, etc.
422-- To facilitate common needs, @"Data.OpenApi.Operation"@ module provides useful helpers.
424-- $validation
425-- While @'ToParamSchema'@ and @'ToSchema'@ provide means to easily obtain schemas for Haskell types,
426-- there is no static mechanism to ensure those instances correspond to the @'ToHttpApiData'@ or @'ToJSON'@ instances.
427--
428-- @"Data.OpenApi.Schema.Validation"@ addresses @'ToJSON'@/@'ToSchema'@ validation.