git.iko.soy/typeable/openapi3
on 443a0ed help sign in
typeable/openapi3/src/Data/Swagger/Internal.hs
1009 lines 37 kB history raw
1{-# LANGUAGE DeriveGeneric #-}
2{-# LANGUAGE DeriveTraversable #-}
3{-# LANGUAGE FlexibleInstances #-}
4{-# LANGUAGE GeneralizedNewtypeDeriving #-}
5{-# LANGUAGE OverloadedStrings #-}
6{-# LANGUAGE RecordWildCards #-}
7{-# LANGUAGE ScopedTypeVariables #-}
8{-# LANGUAGE StandaloneDeriving #-}
9{-# LANGUAGE TemplateHaskell #-}
10module Data.Swagger.Internal where
12import Control.Applicative
13import Control.Monad
14import Data.Aeson
15import Data.Aeson.TH (deriveJSON)
16import Data.Foldable (Foldable)
17import Data.HashMap.Strict (HashMap)
18import qualified Data.HashMap.Strict as HashMap
19import Data.Map (Map)
20import qualified Data.Map as Map
21import Data.Monoid
22import Data.String (fromString)
23import Data.Text (Text)
24import qualified Data.Text as Text
25import Data.Traversable (Traversable)
26import Data.Hashable (Hashable)
27import GHC.Generics (Generic)
28import Network (HostName, PortNumber)
29import Network.HTTP.Media (MediaType)
30import Text.Read (readMaybe)
32import Data.Swagger.Internal.Utils
34-- | This is the root document object for the API specification.
35data Swagger = Swagger
36 { -- | Provides metadata about the API.
37 -- The metadata can be used by the clients if needed.
38 _info :: Info
40 -- | The host (name or ip) serving the API. It MAY include a port.
41 -- If the host is not included, the host serving the documentation is to be used (including the port).
42 , _host :: Maybe Host
44 -- | The base path on which the API is served, which is relative to the host.
45 -- If it is not included, the API is served directly under the host.
46 -- The value MUST start with a leading slash (/).
47 , _basePath :: Maybe FilePath
49 -- | The transfer protocol of the API.
50 -- If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.
51 , _schemes :: Maybe [Scheme]
53 -- | A list of MIME types the APIs can consume.
54 -- This is global to all APIs but can be overridden on specific API calls.
55 , _consumes :: MimeList
57 -- | A list of MIME types the APIs can produce.
58 -- This is global to all APIs but can be overridden on specific API calls.
59 , _produces :: MimeList
61 -- | The available paths and operations for the API.
62 , _paths :: Paths
64 -- | An object to hold data types produced and consumed by operations.
65 , _definitions :: HashMap Text Schema
67 -- | An object to hold parameters that can be used across operations.
68 -- This property does not define global parameters for all operations.
69 , _parameters :: HashMap Text Parameter
71 -- | An object to hold responses that can be used across operations.
72 -- This property does not define global responses for all operations.
73 , _responses :: HashMap Text Response
75 -- | Security scheme definitions that can be used across the specification.
76 , _securityDefinitions :: HashMap Text SecurityScheme
78 -- | A declaration of which security schemes are applied for the API as a whole.
79 -- The list of values describes alternative security schemes that can be used
80 -- (that is, there is a logical OR between the security requirements).
81 -- Individual operations can override this definition.
82 , _security :: [SecurityRequirement]
84 -- | A list of tags used by the specification with additional metadata.
85 -- The order of the tags can be used to reflect on their order by the parsing tools.
86 -- Not all tags that are used by the Operation Object must be declared.
87 -- The tags that are not declared may be organized randomly or based on the tools' logic.
88 -- Each tag name in the list MUST be unique.
89 , _tags :: [Tag]
91 -- | Additional external documentation.
92 , _externalDocs :: Maybe ExternalDocs
93 } deriving (Eq, Show, Generic)
95-- | The object provides metadata about the API.
96-- The metadata can be used by the clients if needed,
97-- and can be presented in the Swagger-UI for convenience.
98data Info = Info
99 { -- | The title of the application.
100 _infoTitle :: Text
102 -- | A short description of the application.
103 -- GFM syntax can be used for rich text representation.
104 , _infoDescription :: Maybe Text
106 -- | The Terms of Service for the API.
107 , _infoTermsOfService :: Maybe Text
109 -- | The contact information for the exposed API.
110 , _infoContact :: Maybe Contact
112 -- | The license information for the exposed API.
113 , _infoLicense :: Maybe License
115 -- | Provides the version of the application API
116 -- (not to be confused with the specification version).
117 , _infoVersion :: Text
118 } deriving (Eq, Show, Generic)
120-- | Contact information for the exposed API.
121data Contact = Contact
122 { -- | The identifying name of the contact person/organization.
123 _contactName :: Maybe Text
125 -- | The URL pointing to the contact information.
126 , _contactUrl :: Maybe URL
128 -- | The email address of the contact person/organization.
129 , _contactEmail :: Maybe Text
130 } deriving (Eq, Show)
132-- | License information for the exposed API.
133data License = License
134 { -- | The license name used for the API.
135 _licenseName :: Text
137 -- | A URL to the license used for the API.
138 , _licenseUrl :: Maybe URL
139 } deriving (Eq, Show)
141-- | The host (name or ip) serving the API. It MAY include a port.
142data Host = Host
143 { _hostName :: HostName -- ^ Host name.
144 , _hostPort :: Maybe PortNumber -- ^ Optional port.
145 } deriving (Eq, Show)
147-- | The transfer protocol of the API.
148data Scheme
149 = Http
150 | Https
151 | Ws
152 | Wss
153 deriving (Eq, Show)
155-- | The available paths and operations for the API.
156data Paths = Paths
157 { -- | Holds the relative paths to the individual endpoints.
158 -- The path is appended to the @'basePath'@ in order to construct the full URL.
159 _pathsMap :: HashMap FilePath PathItem
160 } deriving (Eq, Show, Generic)
162-- | Describes the operations available on a single path.
163-- A @'PathItem'@ may be empty, due to ACL constraints.
164-- The path itself is still exposed to the documentation viewer
165-- but they will not know which operations and parameters are available.
166data PathItem = PathItem
167 { -- | A definition of a GET operation on this path.
168 _pathItemGet :: Maybe Operation
170 -- | A definition of a PUT operation on this path.
171 , _pathItemPut :: Maybe Operation
173 -- | A definition of a POST operation on this path.
174 , _pathItemPost :: Maybe Operation
176 -- | A definition of a DELETE operation on this path.
177 , _pathItemDelete :: Maybe Operation
179 -- | A definition of a OPTIONS operation on this path.
180 , _pathItemOptions :: Maybe Operation
182 -- | A definition of a HEAD operation on this path.
183 , _pathItemHead :: Maybe Operation
185 -- | A definition of a PATCH operation on this path.
186 , _pathItemPatch :: Maybe Operation
188 -- | A list of parameters that are applicable for all the operations described under this path.
189 -- These parameters can be overridden at the operation level, but cannot be removed there.
190 -- The list MUST NOT include duplicated parameters.
191 -- A unique parameter is defined by a combination of a name and location.
192 , _pathItemParameters :: [Referenced Parameter]
193 } deriving (Eq, Show, Generic)
195-- | Describes a single API operation on a path.
196data Operation = Operation
197 { -- | A list of tags for API documentation control.
198 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
199 _operationTags :: [Text]
201 -- | A short summary of what the operation does.
202 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
203 , _operationSummary :: Maybe Text
205 -- | A verbose explanation of the operation behavior.
206 -- GFM syntax can be used for rich text representation.
207 , _operationDescription :: Maybe Text
209 -- | Additional external documentation for this operation.
210 , _operationExternalDocs :: Maybe ExternalDocs
212 -- | Unique string used to identify the operation.
213 -- The id MUST be unique among all operations described in the API.
214 -- Tools and libraries MAY use the it to uniquely identify an operation,
215 -- therefore, it is recommended to follow common programming naming conventions.
216 , _operationOperationId :: Maybe Text
218 -- | A list of MIME types the operation can consume.
219 -- This overrides the @'consumes'@.
220 -- @Just []@ MAY be used to clear the global definition.
221 , _operationConsumes :: Maybe MimeList
223 -- | A list of MIME types the operation can produce.
224 -- This overrides the @'produces'@.
225 -- @Just []@ MAY be used to clear the global definition.
226 , _operationProduces :: Maybe MimeList
228 -- | A list of parameters that are applicable for this operation.
229 -- If a parameter is already defined at the @'PathItem'@,
230 -- the new definition will override it, but can never remove it.
231 -- The list MUST NOT include duplicated parameters.
232 -- A unique parameter is defined by a combination of a name and location.
233 , _operationParameters :: [Referenced Parameter]
235 -- | The list of possible responses as they are returned from executing this operation.
236 , _operationResponses :: Responses
238 -- | The transfer protocol for the operation.
239 -- The value overrides @'schemes'@.
240 , _operationSchemes :: Maybe [Scheme]
242 -- | Declares this operation to be deprecated.
243 -- Usage of the declared operation should be refrained.
244 -- Default value is @False@.
245 , _operationDeprecated :: Maybe Bool
247 -- | A declaration of which security schemes are applied for this operation.
248 -- The list of values describes alternative security schemes that can be used
249 -- (that is, there is a logical OR between the security requirements).
250 -- This definition overrides any declared top-level security.
251 -- To remove a top-level security declaration, @Just []@ can be used.
252 , _operationSecurity :: [SecurityRequirement]
253 } deriving (Eq, Show, Generic)
255newtype MimeList = MimeList { getMimeList :: [MediaType] }
256 deriving (Eq, Show, Monoid)
258-- | Describes a single operation parameter.
259-- A unique parameter is defined by a combination of a name and location.
260data Parameter = Parameter
261 { -- | The name of the parameter.
262 -- Parameter names are case sensitive.
263 _parameterName :: Text
265 -- | A brief description of the parameter.
266 -- This could contain examples of use.
267 -- GFM syntax can be used for rich text representation.
268 , _parameterDescription :: Maybe Text
270 -- | Determines whether this parameter is mandatory.
271 -- If the parameter is in "path", this property is required and its value MUST be true.
272 -- Otherwise, the property MAY be included and its default value is @False@.
273 , _parameterRequired :: Maybe Bool
275 -- | Parameter schema.
276 , _parameterSchema :: ParameterSchema
277 } deriving (Eq, Show, Generic)
279data ParameterSchema
280 = ParameterBody (Referenced Schema)
281 | ParameterOther ParameterOtherSchema
282 deriving (Eq, Show)
284data ParameterOtherSchema = ParameterOtherSchema
285 { -- | The location of the parameter.
286 _parameterOtherSchemaIn :: ParameterLocation
288 -- | The type of the parameter.
289 -- Since the parameter is not located at the request body,
290 -- it is limited to simple types (that is, not an object).
291 -- If type is @'ParamFile'@, the @consumes@ MUST be either
292 -- "multipart/form-data" or " application/x-www-form-urlencoded"
293 -- and the parameter MUST be in @'ParameterFormData'@.
294 , _parameterOtherSchemaType :: ParameterType
296 -- | The extending format for the previously mentioned type.
297 , _parameterOtherSchemaFormat :: Maybe Format
299 -- | Sets the ability to pass empty-valued parameters.
300 -- This is valid only for either @'ParameterQuery'@ or @'ParameterFormData'@
301 -- and allows you to send a parameter with a name only or an empty value.
302 -- Default value is @False@.
303 , _parameterOtherSchemaAllowEmptyValue :: Maybe Bool
305 -- | __Required if type is @'ParamArray'@__.
306 -- Describes the type of items in the array.
307 , _parameterOtherSchemaItems :: Maybe Items
309 -- | Determines the format of the array if @'ParamArray'@ is used.
310 -- Default value is csv.
311 , _parameterOtherSchemaCollectionFormat :: Maybe CollectionFormat
313 , _parameterOtherSchemaCommon :: SchemaCommon
314 } deriving (Eq, Show, Generic)
316data ParameterType
317 = ParamString
318 | ParamNumber
319 | ParamInteger
320 | ParamBoolean
321 | ParamArray
322 | ParamFile
323 deriving (Eq, Show)
325data ParameterLocation
326 = -- | Parameters that are appended to the URL.
327 -- For example, in @/items?id=###@, the query parameter is @id@.
328 ParameterQuery
329 -- | Custom headers that are expected as part of the request.
330 | ParameterHeader
331 -- | Used together with Path Templating, where the parameter value is actually part of the operation's URL.
332 -- This does not include the host or base path of the API.
333 -- For example, in @/items/{itemId}@, the path parameter is @itemId@.
334 | ParameterPath
335 -- | Used to describe the payload of an HTTP request when either @application/x-www-form-urlencoded@
336 -- or @multipart/form-data@ are used as the content type of the request
337 -- (in Swagger's definition, the @consumes@ property of an operation).
338 -- This is the only parameter type that can be used to send files, thus supporting the @'ParamFile'@ type.
339 -- Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation.
340 -- Form parameters have a different format based on the content-type used
341 -- (for further details, consult <http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4>).
342 | ParameterFormData
343 deriving (Eq, Show)
345type Format = Text
347-- | Determines the format of the array.
348data CollectionFormat
349 = CollectionCSV -- ^ Comma separated values: @foo,bar@.
350 | CollectionSSV -- ^ Space separated values: @foo bar@.
351 | CollectionTSV -- ^ Tab separated values: @foo\\tbar@.
352 | CollectionPipes -- ^ Pipe separated values: @foo|bar@.
353 | CollectionMulti -- ^ Corresponds to multiple parameter instances
354 -- instead of multiple values for a single instance @foo=bar&foo=baz@.
355 -- This is valid only for parameters in @'ParameterQuery'@ or @'ParameterFormData'@.
356 deriving (Eq, Show)
358data ItemsType
359 = ItemsString
360 | ItemsNumber
361 | ItemsInteger
362 | ItemsBoolean
363 | ItemsArray
364 deriving (Eq, Show)
366data SchemaType
367 = SchemaArray
368 | SchemaBoolean
369 | SchemaInteger
370 | SchemaNumber
371 | SchemaNull
372 | SchemaObject
373 | SchemaString
374 deriving (Eq, Show)
376-- | Determines the format of the nested array.
377data ItemsCollectionFormat
378 = ItemsCollectionCSV -- ^ Comma separated values: @foo,bar@.
379 | ItemsCollectionSSV -- ^ Space separated values: @foo bar@.
380 | ItemsCollectionTSV -- ^ Tab separated values: @foo\\tbar@.
381 | ItemsCollectionPipes -- ^ Pipe separated values: @foo|bar@.
382 deriving (Eq, Show)
384type ParamName = Text
386data Schema = Schema
387 { _schemaType :: SchemaType
388 , _schemaFormat :: Maybe Format
389 , _schemaTitle :: Maybe Text
390 , _schemaDescription :: Maybe Text
391 , _schemaRequired :: [ParamName]
393 , _schemaItems :: Maybe SchemaItems
394 , _schemaAllOf :: Maybe [Schema]
395 , _schemaProperties :: HashMap Text (Referenced Schema)
396 , _schemaAdditionalProperties :: Maybe Schema
398 , _schemaDiscriminator :: Maybe Text
399 , _schemaReadOnly :: Maybe Bool
400 , _schemaXml :: Maybe Xml
401 , _schemaExternalDocs :: Maybe ExternalDocs
402 , _schemaExample :: Maybe Value
404 , _schemaMaxProperties :: Maybe Integer
405 , _schemaMinProperties :: Maybe Integer
407 , _schemaSchemaCommon :: SchemaCommon
408 } deriving (Eq, Show, Generic)
410data SchemaItems
411 = SchemaItemsObject (Referenced Schema)
412 | SchemaItemsArray [Referenced Schema]
413 deriving (Eq, Show)
415data SchemaCommon = SchemaCommon
416 { -- | Declares the value of the parameter that the server will use if none is provided,
417 -- for example a @"count"@ to control the number of results per page might default to @100@
418 -- if not supplied by the client in the request.
419 -- (Note: "default" has no meaning for required parameters.)
420 -- Unlike JSON Schema this value MUST conform to the defined type for this parameter.
421 _schemaCommonDefault :: Maybe Value
423 , _schemaCommonMaximum :: Maybe Integer
424 , _schemaCommonExclusiveMaximum :: Maybe Bool
425 , _schemaCommonMinimum :: Maybe Integer
426 , _schemaCommonExclusiveMinimum :: Maybe Bool
427 , _schemaCommonMaxLength :: Maybe Integer
428 , _schemaCommonMinLength :: Maybe Integer
429 , _schemaCommonPattern :: Maybe Text
430 , _schemaCommonMaxItems :: Maybe Integer
431 , _schemaCommonMinItems :: Maybe Integer
432 , _schemaCommonUniqueItems :: Maybe Bool
433 , _schemaCommonEnum :: Maybe [Value]
434 , _schemaCommonMultipleOf :: Maybe Integer
435 } deriving (Eq, Show, Generic)
437data Xml = Xml
438 { -- | Replaces the name of the element/attribute used for the described schema property.
439 -- When defined within the @'Items'@ (items), it will affect the name of the individual XML elements within the list.
440 -- When defined alongside type being array (outside the items),
441 -- it will affect the wrapping element and only if wrapped is true.
442 -- If wrapped is false, it will be ignored.
443 _xmlName :: Maybe Text
445 -- | The URL of the namespace definition.
446 -- Value SHOULD be in the form of a URL.
447 , _xmlNamespace :: Maybe Text
449 -- | The prefix to be used for the name.
450 , _xmlPrefix :: Maybe Text
452 -- | Declares whether the property definition translates to an attribute instead of an element.
453 -- Default value is @False@.
454 , _xmlAttribute :: Maybe Bool
456 -- | MAY be used only for an array definition.
457 -- Signifies whether the array is wrapped
458 -- (for example, @\<books\>\<book/\>\<book/\>\</books\>@)
459 -- or unwrapped (@\<book/\>\<book/\>@).
460 -- Default value is @False@.
461 -- The definition takes effect only when defined alongside type being array (outside the items).
462 , _xmlWrapped :: Maybe Bool
463 } deriving (Eq, Show, Generic)
465data Items = Items
466 { -- | The internal type of the array.
467 _itemsType :: ItemsType
469 -- | The extending format for the previously mentioned type.
470 , _itemsFormat :: Maybe Format
472 -- | __Required if type is @'ItemsArray'@.__
473 -- Describes the type of items in the array.
474 , _itemsItems :: Maybe Items
476 -- | Determines the format of the array if type array is used.
477 -- Default value is @'ItemsCollectionCSV'@.
478 , _itemsCollectionFormat :: Maybe ItemsCollectionFormat
480 , _itemsCommon :: SchemaCommon
481 } deriving (Eq, Show, Generic)
483-- | A container for the expected responses of an operation.
484-- The container maps a HTTP response code to the expected response.
485-- It is not expected from the documentation to necessarily cover all possible HTTP response codes,
486-- since they may not be known in advance.
487-- However, it is expected from the documentation to cover a successful operation response and any known errors.
488data Responses = Responses
489 { -- | The documentation of responses other than the ones declared for specific HTTP response codes.
490 -- It can be used to cover undeclared responses.
491 _responsesDefault :: Maybe (Referenced Response)
493 -- | Any HTTP status code can be used as the property name (one property per HTTP status code).
494 -- Describes the expected response for those HTTP status codes.
495 , _responsesResponses :: HashMap HttpStatusCode (Referenced Response)
496 } deriving (Eq, Show, Generic)
498type HttpStatusCode = Int
500-- | Describes a single response from an API Operation.
501data Response = Response
502 { -- | A short description of the response.
503 -- GFM syntax can be used for rich text representation.
504 _responseDescription :: Text
506 -- | A definition of the response structure.
507 -- It can be a primitive, an array or an object.
508 -- If this field does not exist, it means no content is returned as part of the response.
509 -- As an extension to the Schema Object, its root type value may also be "file".
510 -- This SHOULD be accompanied by a relevant produces mime-type.
511 , _responseSchema :: Maybe (Referenced Schema)
513 -- | A list of headers that are sent with the response.
514 , _responseHeaders :: HashMap HeaderName Header
516 -- | An example of the response message.
517 , _responseExamples :: Maybe Example
518 } deriving (Eq, Show, Generic)
520type HeaderName = Text
522data Header = Header
523 { -- | A short description of the header.
524 _headerDescription :: Maybe Text
526 -- | The type of the object.
527 , _headerType :: ItemsType
529 -- | The extending format for the previously mentioned type. See Data Type Formats for further details.
530 , _headerFormat :: Maybe Format
532 -- | __Required if type is @'ItemsArray'@__.
533 -- Describes the type of items in the array.
534 , _headerItems :: Maybe Items
536 -- | Determines the format of the array if type array is used.
537 -- Default value is @'ItemsCollectionCSV'@.
538 , _headerCollectionFormat :: Maybe ItemsCollectionFormat
540 , _headerCommon :: SchemaCommon
541 } deriving (Eq, Show, Generic)
543data Example = Example { getExample :: Map MediaType Value }
544 deriving (Eq, Show)
546-- | The location of the API key.
547data ApiKeyLocation
548 = ApiKeyQuery
549 | ApiKeyHeader
550 deriving (Eq, Show)
552data ApiKeyParams = ApiKeyParams
553 { -- | The name of the header or query parameter to be used.
554 _apiKeyName :: Text
556 -- | The location of the API key.
557 , _apiKeyIn :: ApiKeyLocation
558 } deriving (Eq, Show)
560-- | The authorization URL to be used for OAuth2 flow. This SHOULD be in the form of a URL.
561type AuthorizationURL = Text
563-- | The token URL to be used for OAuth2 flow. This SHOULD be in the form of a URL.
564type TokenURL = Text
566data OAuth2Flow
567 = OAuth2Implicit AuthorizationURL
568 | OAuth2Password TokenURL
569 | OAuth2Application TokenURL
570 | OAuth2AccessCode AuthorizationURL TokenURL
571 deriving (Eq, Show)
573data OAuth2Params = OAuth2Params
574 { -- | The flow used by the OAuth2 security scheme.
575 _oauth2Flow :: OAuth2Flow
577 -- | The available scopes for the OAuth2 security scheme.
578 , _oauth2Scopes :: HashMap Text Text
579 } deriving (Eq, Show, Generic)
581data SecuritySchemeType
582 = SecuritySchemeBasic
583 | SecuritySchemeApiKey ApiKeyParams
584 | SecuritySchemeOAuth2 OAuth2Params
585 deriving (Eq, Show)
587data SecurityScheme = SecurityScheme
588 { -- | The type of the security scheme.
589 _securitySchemeType :: SecuritySchemeType
591 -- | A short description for security scheme.
592 , _securitySchemeDescription :: Maybe Text
593 } deriving (Eq, Show, Generic)
595-- | Lists the required security schemes to execute this operation.
596-- The object can have multiple security schemes declared in it which are all required
597-- (that is, there is a logical AND between the schemes).
598newtype SecurityRequirement = SecurityRequirement
599 { getSecurityRequirement :: HashMap Text [Text]
600 } deriving (Eq, Read, Show, Monoid, ToJSON, FromJSON)
602-- | Allows adding meta data to a single tag that is used by @Operation@.
603-- It is not mandatory to have a @Tag@ per tag used there.
604data Tag = Tag
605 { -- | The name of the tag.
606 _tagName :: Text
608 -- | A short description for the tag.
609 -- GFM syntax can be used for rich text representation.
610 , _tagDescription :: Maybe Text
612 -- | Additional external documentation for this tag.
613 , _tagExternalDocs :: Maybe ExternalDocs
614 } deriving (Eq, Show)
616-- | Allows referencing an external resource for extended documentation.
617data ExternalDocs = ExternalDocs
618 { -- | A short description of the target documentation.
619 -- GFM syntax can be used for rich text representation.
620 _externalDocsDescription :: Maybe Text
622 -- | The URL for the target documentation.
623 , _externalDocsUrl :: URL
624 } deriving (Eq, Show, Generic)
626-- | A simple object to allow referencing other definitions in the specification.
627-- It can be used to reference parameters and responses that are defined at the top level for reuse.
628newtype Reference = Reference { getReference :: Text }
629 deriving (Eq, Show)
631data Referenced a
632 = Ref Reference
633 | Inline a
634 deriving (Eq, Show)
636newtype URL = URL { getUrl :: Text } deriving (Eq, Show, ToJSON, FromJSON)
638-- =======================================================================
639-- Monoid instances
640-- =======================================================================
642instance Monoid Swagger where
643 mempty = genericMempty
644 mappend = genericMappend
646instance Monoid Info where
647 mempty = genericMempty
648 mappend = genericMappend
650instance Monoid Paths where
651 mempty = genericMempty
652 mappend = genericMappend
654instance Monoid PathItem where
655 mempty = genericMempty
656 mappend = genericMappend
658instance Monoid Schema where
659 mempty = genericMempty
660 mappend = genericMappend
662instance Monoid SchemaCommon where
663 mempty = genericMempty
664 mappend = genericMappend
666instance Monoid Parameter where
667 mempty = genericMempty
668 mappend = genericMappend
670instance Monoid ParameterOtherSchema where
671 mempty = genericMempty
672 mappend = genericMappend
674instance Monoid Responses where
675 mempty = genericMempty
676 mappend = genericMappend
678instance Monoid Response where
679 mempty = genericMempty
680 mappend = genericMappend
682instance Monoid ExternalDocs where
683 mempty = genericMempty
684 mappend = genericMappend
686instance Monoid Operation where
687 mempty = genericMempty
688 mappend = genericMappend
690-- =======================================================================
691-- SwaggerMonoid helper instances
692-- =======================================================================
694instance SwaggerMonoid Info
695instance SwaggerMonoid Paths
696instance SwaggerMonoid PathItem
697instance SwaggerMonoid Schema
698instance SwaggerMonoid SchemaCommon
699instance SwaggerMonoid Parameter
700instance SwaggerMonoid ParameterOtherSchema
701instance SwaggerMonoid Responses
702instance SwaggerMonoid Response
703instance SwaggerMonoid ExternalDocs
704instance SwaggerMonoid Operation
706instance SwaggerMonoid MimeList
707deriving instance SwaggerMonoid URL
709instance SwaggerMonoid SchemaType where
710 swaggerMempty = SchemaNull
711 swaggerMappend _ y = y
713instance SwaggerMonoid ParameterType where
714 swaggerMempty = ParamString
715 swaggerMappend _ y = y
717instance SwaggerMonoid ParameterLocation where
718 swaggerMempty = ParameterQuery
719 swaggerMappend _ y = y
721instance SwaggerMonoid (HashMap Text Schema) where
722 swaggerMempty = HashMap.empty
723 swaggerMappend = HashMap.unionWith mappend
725instance SwaggerMonoid (HashMap Text (Referenced Schema)) where
726 swaggerMempty = HashMap.empty
727 swaggerMappend = HashMap.unionWith swaggerMappend
729instance Monoid a => SwaggerMonoid (Referenced a) where
730 swaggerMempty = Inline mempty
731 swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
732 swaggerMappend _ y = y
734instance SwaggerMonoid (HashMap Text Parameter) where
735 swaggerMempty = HashMap.empty
736 swaggerMappend = HashMap.unionWith mappend
738instance SwaggerMonoid (HashMap Text Response) where
739 swaggerMempty = HashMap.empty
740 swaggerMappend = flip HashMap.union
742instance SwaggerMonoid (HashMap Text SecurityScheme) where
743 swaggerMempty = HashMap.empty
744 swaggerMappend = flip HashMap.union
746instance SwaggerMonoid (HashMap FilePath PathItem) where
747 swaggerMempty = HashMap.empty
748 swaggerMappend = HashMap.unionWith mappend
750instance SwaggerMonoid (HashMap HeaderName Header) where
751 swaggerMempty = HashMap.empty
752 swaggerMappend = flip HashMap.union
754instance SwaggerMonoid (HashMap HttpStatusCode (Referenced Response)) where
755 swaggerMempty = HashMap.empty
756 swaggerMappend = flip HashMap.union
758instance SwaggerMonoid ParameterSchema where
759 swaggerMempty = ParameterOther swaggerMempty
760 swaggerMappend (ParameterBody x) (ParameterBody y) = ParameterBody (swaggerMappend x y)
761 swaggerMappend (ParameterOther x) (ParameterOther y) = ParameterOther (swaggerMappend x y)
762 swaggerMappend _ y = y
764-- =======================================================================
765-- TH derived ToJSON and FromJSON instances
766-- =======================================================================
768deriveJSON (jsonPrefix "Parameter") ''ParameterLocation
769deriveJSON (jsonPrefix "Param") ''ParameterType
770deriveJSON' ''Info
771deriveJSON' ''Contact
772deriveJSON' ''License
773deriveJSON (jsonPrefix "Schema") ''SchemaType
774deriveJSON (jsonPrefix "Items") ''ItemsType
775deriveJSON (jsonPrefix "ItemsCollection") ''ItemsCollectionFormat
776deriveJSON (jsonPrefix "Collection") ''CollectionFormat
777deriveJSON (jsonPrefix "ApiKey") ''ApiKeyLocation
778deriveJSON (jsonPrefix "apiKey") ''ApiKeyParams
779deriveJSON' ''SchemaCommon
780deriveJSONDefault ''Scheme
781deriveJSON' ''Tag
782deriveJSON' ''ExternalDocs
784deriveToJSON' ''Operation
785deriveToJSON' ''Response
786deriveToJSON' ''PathItem
787deriveToJSON' ''Xml
789-- =======================================================================
790-- Manual ToJSON instances
791-- =======================================================================
793instance ToJSON OAuth2Flow where
794 toJSON (OAuth2Implicit authUrl) = object
795 [ "flow" .= ("implicit" :: Text)
796 , "authorizationUrl" .= authUrl ]
797 toJSON (OAuth2Password tokenUrl) = object
798 [ "flow" .= ("password" :: Text)
799 , "tokenUrl" .= tokenUrl ]
800 toJSON (OAuth2Application tokenUrl) = object
801 [ "flow" .= ("application" :: Text)
802 , "tokenUrl" .= tokenUrl ]
803 toJSON (OAuth2AccessCode authUrl tokenUrl) = object
804 [ "flow" .= ("accessCode" :: Text)
805 , "authorizationUrl" .= authUrl
806 , "tokenUrl" .= tokenUrl ]
808instance ToJSON OAuth2Params where
809 toJSON = genericToJSONWithSub "flow" (jsonPrefix "oauth2")
811instance ToJSON SecuritySchemeType where
812 toJSON SecuritySchemeBasic
813 = object [ "type" .= ("basic" :: Text) ]
814 toJSON (SecuritySchemeApiKey params)
815 = toJSON params
816 <+> object [ "type" .= ("apiKey" :: Text) ]
817 toJSON (SecuritySchemeOAuth2 params)
818 = toJSON params
819 <+> object [ "type" .= ("oauth2" :: Text) ]
821instance ToJSON Swagger where
822 toJSON = addVersion . genericToJSON (jsonPrefix "")
823 where
824 addVersion (Object o) = Object (HashMap.insert "swagger" "2.0" o)
825 addVersion _ = error "impossible"
827instance ToJSON SecurityScheme where
828 toJSON = genericToJSONWithSub "type" (jsonPrefix "securityScheme")
830instance ToJSON Schema where
831 toJSON = genericToJSONWithSub "schemaCommon" (jsonPrefix "schema")
833instance ToJSON Header where
834 toJSON = genericToJSONWithSub "common" (jsonPrefix "header")
836instance ToJSON Items where
837 toJSON = genericToJSONWithSub "common" (jsonPrefix "items")
839instance ToJSON Host where
840 toJSON (Host host mport) = toJSON $
841 case mport of
842 Nothing -> host
843 Just port -> host ++ ":" ++ show port
845instance ToJSON Paths where
846 toJSON (Paths m) = toJSON m
848instance ToJSON MimeList where
849 toJSON (MimeList xs) = toJSON (map show xs)
851instance ToJSON Parameter where
852 toJSON = genericToJSONWithSub "schema" (jsonPrefix "parameter")
854instance ToJSON ParameterSchema where
855 toJSON (ParameterBody s) = object [ "in" .= ("body" :: Text), "schema" .= s ]
856 toJSON (ParameterOther s) = toJSON s
858instance ToJSON ParameterOtherSchema where
859 toJSON = genericToJSONWithSub "common" (jsonPrefix "parameterOtherSchema")
861instance ToJSON SchemaItems where
862 toJSON (SchemaItemsObject x) = toJSON x
863 toJSON (SchemaItemsArray xs) = toJSON xs
865instance ToJSON Responses where
866 toJSON (Responses def rs) = toJSON (hashMapMapKeys show rs) <+> object [ "default" .= def ]
868instance ToJSON Example where
869 toJSON = toJSON . Map.mapKeys show . getExample
871instance ToJSON Reference where
872 toJSON (Reference ref) = object [ "$ref" .= ref ]
874instance ToJSON a => ToJSON (Referenced a) where
875 toJSON (Ref ref) = toJSON ref
876 toJSON (Inline x) = toJSON x
878-- =======================================================================
879-- Manual FromJSON instances
880-- =======================================================================
882instance FromJSON OAuth2Flow where
883 parseJSON (Object o) = do
884 (flow :: Text) <- o .: "flow"
885 case flow of
886 "implicit" -> OAuth2Implicit <$> o .: "authorizationUrl"
887 "password" -> OAuth2Password <$> o .: "tokenUrl"
888 "application" -> OAuth2Application <$> o .: "tokenUrl"
889 "accessCode" -> OAuth2AccessCode
890 <$> o .: "authorizationUrl"
891 <*> o .: "tokenUrl"
892 _ -> empty
893 parseJSON _ = empty
895instance FromJSON OAuth2Params where
896 parseJSON = genericParseJSONWithSub "flow" (jsonPrefix "oauth2")
898instance FromJSON SecuritySchemeType where
899 parseJSON json@(Object o) = do
900 (t :: Text) <- o .: "type"
901 case t of
902 "basic" -> pure SecuritySchemeBasic
903 "apiKey" -> SecuritySchemeApiKey <$> parseJSON json
904 "oauth2" -> SecuritySchemeOAuth2 <$> parseJSON json
905 _ -> empty
906 parseJSON _ = empty
908instance FromJSON Swagger where
909 parseJSON json@(Object o) = do
910 (version :: Text) <- o .: "swagger"
911 when (version /= "2.0") empty
912 (genericParseJSON (jsonPrefix "")
913 `withDefaults` [ "consumes" .= (mempty :: MimeList)
914 , "produces" .= (mempty :: MimeList)
915 , "security" .= ([] :: [SecurityRequirement])
916 , "tags" .= ([] :: [Tag])
917 , "definitions" .= (mempty :: HashMap Text Schema)
918 , "parameters" .= (mempty :: HashMap Text Parameter)
919 , "responses" .= (mempty :: HashMap Text Response)
920 , "securityDefinitions" .= (mempty :: HashMap Text SecurityScheme)
921 ] ) json
922 parseJSON _ = empty
924instance FromJSON SecurityScheme where
925 parseJSON = genericParseJSONWithSub "type" (jsonPrefix "securityScheme")
927instance FromJSON Schema where
928 parseJSON = genericParseJSONWithSub "schemaCommon" (jsonPrefix "schema")
929 `withDefaults` [ "properties" .= (mempty :: HashMap Text Schema)
930 , "required" .= ([] :: [ParamName]) ]
932instance FromJSON Header where
933 parseJSON = genericParseJSONWithSub "common" (jsonPrefix "header")
935instance FromJSON Items where
936 parseJSON = genericParseJSONWithSub "common" (jsonPrefix "items")
938instance FromJSON Host where
939 parseJSON (String s) =
940 case fromInteger <$> readMaybe portStr of
941 Nothing | not (null portStr) -> fail $ "Invalid port `" ++ portStr ++ "'"
942 mport -> pure $ Host host mport
943 where
944 (hostText, portText) = Text.breakOn ":" s
945 [host, portStr] = map Text.unpack [hostText, portText]
946 parseJSON _ = empty
948instance FromJSON Paths where
949 parseJSON json = Paths <$> parseJSON json
951instance FromJSON MimeList where
952 parseJSON json = (MimeList . map fromString) <$> parseJSON json
954instance FromJSON Parameter where
955 parseJSON = genericParseJSONWithSub "schema" (jsonPrefix "parameter")
957instance FromJSON ParameterSchema where
958 parseJSON json@(Object o) = do
959 (i :: Text) <- o .: "in"
960 case i of
961 "body" -> do
962 schema <- o .: "schema"
963 ParameterBody <$> parseJSON schema
964 _ -> ParameterOther <$> parseJSON json
965 parseJSON _ = empty
967instance FromJSON ParameterOtherSchema where
968 parseJSON = genericParseJSONWithSub "common" (jsonPrefix "parameterOtherSchema")
970instance FromJSON SchemaItems where
971 parseJSON json@(Object _) = SchemaItemsObject <$> parseJSON json
972 parseJSON json@(Array _) = SchemaItemsArray <$> parseJSON json
973 parseJSON _ = empty
975instance FromJSON Responses where
976 parseJSON (Object o) = Responses
977 <$> o .:? "default"
978 <*> (parseJSON (Object (HashMap.delete "default" o)) >>= hashMapReadKeys)
979 parseJSON _ = empty
981instance FromJSON Example where
982 parseJSON json = do
983 m <- parseJSON json
984 pure $ Example (Map.mapKeys fromString m)
986instance FromJSON Response where
987 parseJSON = genericParseJSON (jsonPrefix "response")
988 `withDefaults` [ "headers" .= (mempty :: HashMap HeaderName Header) ]
990instance FromJSON Operation where
991 parseJSON = genericParseJSON (jsonPrefix "operation")
992 `withDefaults` [ "security" .= ([] :: [SecurityRequirement]) ]
994instance FromJSON PathItem where
995 parseJSON = genericParseJSON (jsonPrefix "pathItem")
996 `withDefaults` [ "parameters" .= ([] :: [Parameter]) ]
998instance FromJSON Reference where
999 parseJSON (Object o) = Reference <$> o .: "$ref"
1000 parseJSON _ = empty
1002instance FromJSON a => FromJSON (Referenced a) where
1003 parseJSON json
1004 = Ref <$> parseJSON json
1005 <|> Inline <$> parseJSON json
1007instance FromJSON Xml where
1008 parseJSON = genericParseJSON (jsonPrefix "xml")