git.iko.soy/typeable/openapi3
on 67f8475 help sign in
typeable/openapi3/src/Data/Swagger/Internal.hs
1190 lines 45 kB history raw
1{-# LANGUAGE CPP #-}
2{-# LANGUAGE DeriveDataTypeable #-}
3{-# LANGUAGE DeriveFunctor #-}
4{-# LANGUAGE DeriveGeneric #-}
5{-# LANGUAGE DeriveTraversable #-}
6{-# LANGUAGE FlexibleContexts #-}
7{-# LANGUAGE FlexibleInstances #-}
8{-# LANGUAGE GADTs #-}
9{-# LANGUAGE GeneralizedNewtypeDeriving #-}
10{-# LANGUAGE OverloadedStrings #-}
11{-# LANGUAGE RecordWildCards #-}
12{-# LANGUAGE ScopedTypeVariables #-}
13{-# LANGUAGE StandaloneDeriving #-}
14{-# LANGUAGE UndecidableInstances #-}
15#include "overlapping-compat.h"
16module Data.Swagger.Internal where
18import Prelude ()
19import Prelude.Compat
21import Control.Applicative
22import Control.Monad
23import Data.Aeson
24import qualified Data.Aeson.Types as JSON
25import Data.Data (Data(..), Typeable, mkConstr, mkDataType, Fixity(..), Constr, DataType, constrIndex)
26import Data.HashMap.Strict (HashMap)
27import qualified Data.HashMap.Strict as HashMap
28import Data.Map (Map)
29import qualified Data.Map as Map
30import Data.Monoid
31import Data.Scientific (Scientific)
32import Data.Set (Set)
33import Data.String (IsString(..))
34import Data.Text (Text)
35import qualified Data.Text as Text
36import GHC.Generics (Generic)
37import Network (HostName, PortNumber)
38import Network.HTTP.Media (MediaType)
39import Text.Read (readMaybe)
41import Data.Swagger.Internal.Utils
43-- | A list of definitions that can be used in references.
44type Definitions = HashMap Text
46-- | This is the root document object for the API specification.
47data Swagger = Swagger
48 { -- | Provides metadata about the API.
49 -- The metadata can be used by the clients if needed.
50 _swaggerInfo :: Info
52 -- | The host (name or ip) serving the API. It MAY include a port.
53 -- If the host is not included, the host serving the documentation is to be used (including the port).
54 , _swaggerHost :: Maybe Host
56 -- | The base path on which the API is served, which is relative to the host.
57 -- If it is not included, the API is served directly under the host.
58 -- The value MUST start with a leading slash (/).
59 , _swaggerBasePath :: Maybe FilePath
61 -- | The transfer protocol of the API.
62 -- If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.
63 , _swaggerSchemes :: Maybe [Scheme]
65 -- | A list of MIME types the APIs can consume.
66 -- This is global to all APIs but can be overridden on specific API calls.
67 , _swaggerConsumes :: MimeList
69 -- | A list of MIME types the APIs can produce.
70 -- This is global to all APIs but can be overridden on specific API calls.
71 , _swaggerProduces :: MimeList
73 -- | The available paths and operations for the API.
74 -- Holds the relative paths to the individual endpoints.
75 -- The path is appended to the @'basePath'@ in order to construct the full URL.
76 , _swaggerPaths :: HashMap FilePath PathItem
78 -- | An object to hold data types produced and consumed by operations.
79 , _swaggerDefinitions :: Definitions Schema
81 -- | An object to hold parameters that can be used across operations.
82 -- This property does not define global parameters for all operations.
83 , _swaggerParameters :: Definitions Param
85 -- | An object to hold responses that can be used across operations.
86 -- This property does not define global responses for all operations.
87 , _swaggerResponses :: Definitions Response
89 -- | Security scheme definitions that can be used across the specification.
90 , _swaggerSecurityDefinitions :: Definitions SecurityScheme
92 -- | A declaration of which security schemes are applied for the API as a whole.
93 -- The list of values describes alternative security schemes that can be used
94 -- (that is, there is a logical OR between the security requirements).
95 -- Individual operations can override this definition.
96 , _swaggerSecurity :: [SecurityRequirement]
98 -- | A list of tags used by the specification with additional metadata.
99 -- The order of the tags can be used to reflect on their order by the parsing tools.
100 -- Not all tags that are used by the Operation Object must be declared.
101 -- The tags that are not declared may be organized randomly or based on the tools' logic.
102 -- Each tag name in the list MUST be unique.
103 , _swaggerTags :: Set Tag
105 -- | Additional external documentation.
106 , _swaggerExternalDocs :: Maybe ExternalDocs
107 } deriving (Eq, Show, Generic, Data, Typeable)
109-- | The object provides metadata about the API.
110-- The metadata can be used by the clients if needed,
111-- and can be presented in the Swagger-UI for convenience.
112data Info = Info
113 { -- | The title of the application.
114 _infoTitle :: Text
116 -- | A short description of the application.
117 -- GFM syntax can be used for rich text representation.
118 , _infoDescription :: Maybe Text
120 -- | The Terms of Service for the API.
121 , _infoTermsOfService :: Maybe Text
123 -- | The contact information for the exposed API.
124 , _infoContact :: Maybe Contact
126 -- | The license information for the exposed API.
127 , _infoLicense :: Maybe License
129 -- | Provides the version of the application API
130 -- (not to be confused with the specification version).
131 , _infoVersion :: Text
132 } deriving (Eq, Show, Generic, Data, Typeable)
134-- | Contact information for the exposed API.
135data Contact = Contact
136 { -- | The identifying name of the contact person/organization.
137 _contactName :: Maybe Text
139 -- | The URL pointing to the contact information.
140 , _contactUrl :: Maybe URL
142 -- | The email address of the contact person/organization.
143 , _contactEmail :: Maybe Text
144 } deriving (Eq, Show, Generic, Data, Typeable)
146-- | License information for the exposed API.
147data License = License
148 { -- | The license name used for the API.
149 _licenseName :: Text
151 -- | A URL to the license used for the API.
152 , _licenseUrl :: Maybe URL
153 } deriving (Eq, Show, Generic, Data, Typeable)
155instance IsString License where
156 fromString s = License (fromString s) Nothing
158-- | The host (name or ip) serving the API. It MAY include a port.
159data Host = Host
160 { _hostName :: HostName -- ^ Host name.
161 , _hostPort :: Maybe PortNumber -- ^ Optional port.
162 } deriving (Eq, Show, Generic, Typeable)
164instance IsString Host where
165 fromString s = Host s Nothing
167hostConstr :: Constr
168hostConstr = mkConstr hostDataType "Host" [] Prefix
170hostDataType :: DataType
171hostDataType = mkDataType "Data.Swagger.Host" [hostConstr]
173instance Data Host where
174 gunfold k z c = case constrIndex c of
175 1 -> k (k (z (\name mport -> Host name (fromInteger <$> mport))))
176 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type Host."
177 toConstr (Host _ _) = hostConstr
178 dataTypeOf _ = hostDataType
180-- | The transfer protocol of the API.
181data Scheme
182 = Http
183 | Https
184 | Ws
185 | Wss
186 deriving (Eq, Show, Generic, Data, Typeable)
188-- | Describes the operations available on a single path.
189-- A @'PathItem'@ may be empty, due to ACL constraints.
190-- The path itself is still exposed to the documentation viewer
191-- but they will not know which operations and parameters are available.
192data PathItem = PathItem
193 { -- | A definition of a GET operation on this path.
194 _pathItemGet :: Maybe Operation
196 -- | A definition of a PUT operation on this path.
197 , _pathItemPut :: Maybe Operation
199 -- | A definition of a POST operation on this path.
200 , _pathItemPost :: Maybe Operation
202 -- | A definition of a DELETE operation on this path.
203 , _pathItemDelete :: Maybe Operation
205 -- | A definition of a OPTIONS operation on this path.
206 , _pathItemOptions :: Maybe Operation
208 -- | A definition of a HEAD operation on this path.
209 , _pathItemHead :: Maybe Operation
211 -- | A definition of a PATCH operation on this path.
212 , _pathItemPatch :: Maybe Operation
214 -- | A list of parameters that are applicable for all the operations described under this path.
215 -- These parameters can be overridden at the operation level, but cannot be removed there.
216 -- The list MUST NOT include duplicated parameters.
217 -- A unique parameter is defined by a combination of a name and location.
218 , _pathItemParameters :: [Referenced Param]
219 } deriving (Eq, Show, Generic, Data, Typeable)
221-- | Describes a single API operation on a path.
222data Operation = Operation
223 { -- | A list of tags for API documentation control.
224 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
225 _operationTags :: Set TagName
227 -- | A short summary of what the operation does.
228 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
229 , _operationSummary :: Maybe Text
231 -- | A verbose explanation of the operation behavior.
232 -- GFM syntax can be used for rich text representation.
233 , _operationDescription :: Maybe Text
235 -- | Additional external documentation for this operation.
236 , _operationExternalDocs :: Maybe ExternalDocs
238 -- | Unique string used to identify the operation.
239 -- The id MUST be unique among all operations described in the API.
240 -- Tools and libraries MAY use the it to uniquely identify an operation,
241 -- therefore, it is recommended to follow common programming naming conventions.
242 , _operationOperationId :: Maybe Text
244 -- | A list of MIME types the operation can consume.
245 -- This overrides the @'consumes'@.
246 -- @Just []@ MAY be used to clear the global definition.
247 , _operationConsumes :: Maybe MimeList
249 -- | A list of MIME types the operation can produce.
250 -- This overrides the @'produces'@.
251 -- @Just []@ MAY be used to clear the global definition.
252 , _operationProduces :: Maybe MimeList
254 -- | A list of parameters that are applicable for this operation.
255 -- If a parameter is already defined at the @'PathItem'@,
256 -- the new definition will override it, but can never remove it.
257 -- The list MUST NOT include duplicated parameters.
258 -- A unique parameter is defined by a combination of a name and location.
259 , _operationParameters :: [Referenced Param]
261 -- | The list of possible responses as they are returned from executing this operation.
262 , _operationResponses :: Responses
264 -- | The transfer protocol for the operation.
265 -- The value overrides @'schemes'@.
266 , _operationSchemes :: Maybe [Scheme]
268 -- | Declares this operation to be deprecated.
269 -- Usage of the declared operation should be refrained.
270 -- Default value is @False@.
271 , _operationDeprecated :: Maybe Bool
273 -- | A declaration of which security schemes are applied for this operation.
274 -- The list of values describes alternative security schemes that can be used
275 -- (that is, there is a logical OR between the security requirements).
276 -- This definition overrides any declared top-level security.
277 -- To remove a top-level security declaration, @Just []@ can be used.
278 , _operationSecurity :: [SecurityRequirement]
279 } deriving (Eq, Show, Generic, Data, Typeable)
281newtype MimeList = MimeList { getMimeList :: [MediaType] }
282 deriving (Eq, Show, Monoid, Typeable)
284mimeListConstr :: Constr
285mimeListConstr = mkConstr mimeListDataType "MimeList" ["getMimeList"] Prefix
287mimeListDataType :: DataType
288mimeListDataType = mkDataType "Data.Swagger.MimeList" [mimeListConstr]
290instance Data MimeList where
291 gunfold k z c = case constrIndex c of
292 1 -> k (z (\xs -> MimeList (map fromString xs)))
293 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type MimeList."
294 toConstr (MimeList _) = mimeListConstr
295 dataTypeOf _ = mimeListDataType
297-- | Describes a single operation parameter.
298-- A unique parameter is defined by a combination of a name and location.
299data Param = Param
300 { -- | The name of the parameter.
301 -- Parameter names are case sensitive.
302 _paramName :: Text
304 -- | A brief description of the parameter.
305 -- This could contain examples of use.
306 -- GFM syntax can be used for rich text representation.
307 , _paramDescription :: Maybe Text
309 -- | Determines whether this parameter is mandatory.
310 -- If the parameter is in "path", this property is required and its value MUST be true.
311 -- Otherwise, the property MAY be included and its default value is @False@.
312 , _paramRequired :: Maybe Bool
314 -- | Parameter schema.
315 , _paramSchema :: ParamAnySchema
316 } deriving (Eq, Show, Generic, Data, Typeable)
318data ParamAnySchema
319 = ParamBody (Referenced Schema)
320 | ParamOther ParamOtherSchema
321 deriving (Eq, Show, Generic, Data, Typeable)
323data ParamOtherSchema = ParamOtherSchema
324 { -- | The location of the parameter.
325 _paramOtherSchemaIn :: ParamLocation
327 -- | Sets the ability to pass empty-valued parameters.
328 -- This is valid only for either @'ParamQuery'@ or @'ParamFormData'@
329 -- and allows you to send a parameter with a name only or an empty value.
330 -- Default value is @False@.
331 , _paramOtherSchemaAllowEmptyValue :: Maybe Bool
333 , _paramOtherSchemaParamSchema :: ParamSchema ParamOtherSchema
334 } deriving (Eq, Show, Generic, Data, Typeable)
336-- | Items for @'SwaggerArray'@ schemas.
337--
338-- @'SwaggerItemsPrimitive'@ should be used only for query params, headers and path pieces.
339-- The @'CollectionFormat' t@ parameter specifies how elements of an array should be displayed.
340-- Note that @fmt@ in @'SwaggerItemsPrimitive' fmt schema@ specifies format for elements of type @schema@.
341-- This is different from the original Swagger's <http://swagger.io/specification/#itemsObject Items Object>.
342--
343-- @'SwaggerItemsObject'@ should be used to specify homogenous array @'Schema'@s.
344--
345-- @'SwaggerItemsArray'@ should be used to specify tuple @'Schema'@s.
346data SwaggerItems t where
347 SwaggerItemsPrimitive :: Maybe (CollectionFormat t) -> ParamSchema t -> SwaggerItems t
348 SwaggerItemsObject :: Referenced Schema -> SwaggerItems Schema
349 SwaggerItemsArray :: [Referenced Schema] -> SwaggerItems Schema
350 deriving (Typeable)
352deriving instance Eq (SwaggerItems t)
353deriving instance Show (SwaggerItems t)
354--deriving instance Typeable (SwaggerItems t)
356swaggerItemsPrimitiveConstr :: Constr
357swaggerItemsPrimitiveConstr = mkConstr swaggerItemsDataType "SwaggerItemsPrimitive" [] Prefix
359swaggerItemsDataType :: DataType
360swaggerItemsDataType = mkDataType "Data.Swagger.SwaggerItems" [swaggerItemsPrimitiveConstr]
362instance OVERLAPPABLE_ Data t => Data (SwaggerItems t) where
363 gunfold k z c = case constrIndex c of
364 1 -> k (k (z SwaggerItemsPrimitive))
365 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems t)."
366 toConstr _ = swaggerItemsPrimitiveConstr
367 dataTypeOf _ = swaggerItemsDataType
369deriving instance Data (SwaggerItems Schema)
371data SwaggerType t where
372 SwaggerString :: SwaggerType t
373 SwaggerNumber :: SwaggerType t
374 SwaggerInteger :: SwaggerType t
375 SwaggerBoolean :: SwaggerType t
376 SwaggerArray :: SwaggerType t
377 SwaggerFile :: SwaggerType ParamOtherSchema
378 SwaggerNull :: SwaggerType Schema
379 SwaggerObject :: SwaggerType Schema
380 deriving (Typeable)
382deriving instance Eq (SwaggerType t)
383deriving instance Show (SwaggerType t)
385swaggerTypeConstr :: Data (SwaggerType t) => SwaggerType t -> Constr
386swaggerTypeConstr t = mkConstr (dataTypeOf t) (show t) [] Prefix
388swaggerTypeDataType :: Data (SwaggerType t) => SwaggerType t -> DataType
389swaggerTypeDataType _ = mkDataType "Data.Swagger.SwaggerType" swaggerTypeConstrs
391swaggerCommonTypes :: [SwaggerType t]
392swaggerCommonTypes = [SwaggerString, SwaggerNumber, SwaggerInteger, SwaggerBoolean, SwaggerArray]
394swaggerParamTypes :: [SwaggerType ParamOtherSchema]
395swaggerParamTypes = swaggerCommonTypes ++ [SwaggerFile]
397swaggerSchemaTypes :: [SwaggerType Schema]
398swaggerSchemaTypes = swaggerCommonTypes ++ [error "SwaggerFile is invalid SwaggerType Schema", SwaggerNull, SwaggerObject]
400swaggerTypeConstrs :: [Constr]
401swaggerTypeConstrs = map swaggerTypeConstr (swaggerCommonTypes :: [SwaggerType Schema])
402 ++ [swaggerTypeConstr SwaggerFile, swaggerTypeConstr SwaggerNull, swaggerTypeConstr SwaggerObject]
404instance OVERLAPPABLE_ Typeable t => Data (SwaggerType t) where
405 gunfold = gunfoldEnum "SwaggerType" swaggerCommonTypes
406 toConstr = swaggerTypeConstr
407 dataTypeOf = swaggerTypeDataType
409instance OVERLAPPABLE_ Data (SwaggerType ParamOtherSchema) where
410 gunfold = gunfoldEnum "SwaggerType ParamOtherSchema" swaggerParamTypes
411 toConstr = swaggerTypeConstr
412 dataTypeOf = swaggerTypeDataType
414instance OVERLAPPABLE_ Data (SwaggerType Schema) where
415 gunfold = gunfoldEnum "SwaggerType Schema" swaggerSchemaTypes
416 toConstr = swaggerTypeConstr
417 dataTypeOf = swaggerTypeDataType
419data ParamLocation
420 = -- | Parameters that are appended to the URL.
421 -- For example, in @/items?id=###@, the query parameter is @id@.
422 ParamQuery
423 -- | Custom headers that are expected as part of the request.
424 | ParamHeader
425 -- | Used together with Path Templating, where the parameter value is actually part of the operation's URL.
426 -- This does not include the host or base path of the API.
427 -- For example, in @/items/{itemId}@, the path parameter is @itemId@.
428 | ParamPath
429 -- | Used to describe the payload of an HTTP request when either @application/x-www-form-urlencoded@
430 -- or @multipart/form-data@ are used as the content type of the request
431 -- (in Swagger's definition, the @consumes@ property of an operation).
432 -- This is the only parameter type that can be used to send files, thus supporting the @'ParamFile'@ type.
433 -- Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation.
434 -- Form parameters have a different format based on the content-type used
435 -- (for further details, consult <http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4>).
436 | ParamFormData
437 deriving (Eq, Show, Generic, Data, Typeable)
439type Format = Text
441-- | Determines the format of the array.
442data CollectionFormat t where
443 -- Comma separated values: @foo,bar@.
444 CollectionCSV :: CollectionFormat t
445 -- Space separated values: @foo bar@.
446 CollectionSSV :: CollectionFormat t
447 -- Tab separated values: @foo\\tbar@.
448 CollectionTSV :: CollectionFormat t
449 -- Pipe separated values: @foo|bar@.
450 CollectionPipes :: CollectionFormat t
451 -- Corresponds to multiple parameter instances
452 -- instead of multiple values for a single instance @foo=bar&foo=baz@.
453 -- This is valid only for parameters in @'ParamQuery'@ or @'ParamFormData'@.
454 CollectionMulti :: CollectionFormat ParamOtherSchema
455 deriving (Typeable)
457deriving instance Eq (CollectionFormat t)
458deriving instance Show (CollectionFormat t)
460collectionFormatConstr :: CollectionFormat t -> Constr
461collectionFormatConstr cf = mkConstr collectionFormatDataType (show cf) [] Prefix
463collectionFormatDataType :: DataType
464collectionFormatDataType = mkDataType "Data.Swagger.CollectionFormat" $
465 map collectionFormatConstr collectionCommonFormats
467collectionCommonFormats :: [CollectionFormat t]
468collectionCommonFormats = [ CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes ]
470instance OVERLAPPABLE_ Data t => Data (CollectionFormat t) where
471 gunfold = gunfoldEnum "CollectionFormat" collectionCommonFormats
472 toConstr = collectionFormatConstr
473 dataTypeOf _ = collectionFormatDataType
475deriving instance OVERLAPPABLE_ Data (CollectionFormat ParamOtherSchema)
477type ParamName = Text
479data Schema = Schema
480 { _schemaTitle :: Maybe Text
481 , _schemaDescription :: Maybe Text
482 , _schemaRequired :: [ParamName]
484 , _schemaAllOf :: Maybe [Schema]
485 , _schemaProperties :: HashMap Text (Referenced Schema)
486 , _schemaAdditionalProperties :: Maybe Schema
488 , _schemaDiscriminator :: Maybe Text
489 , _schemaReadOnly :: Maybe Bool
490 , _schemaXml :: Maybe Xml
491 , _schemaExternalDocs :: Maybe ExternalDocs
492 , _schemaExample :: Maybe Value
494 , _schemaMaxProperties :: Maybe Integer
495 , _schemaMinProperties :: Maybe Integer
497 , _schemaParamSchema :: ParamSchema Schema
498 } deriving (Eq, Show, Generic, Data, Typeable)
500-- | A @'Schema'@ with an optional name.
501-- This name can be used in references.
502data NamedSchema = NamedSchema
503 { _namedSchemaName :: Maybe Text
504 , _namedSchemaSchema :: Schema
505 } deriving (Eq, Show, Generic, Data, Typeable)
507-- | Regex pattern for @string@ type.
508type Pattern = Text
510data ParamSchema t = ParamSchema
511 { -- | Declares the value of the parameter that the server will use if none is provided,
512 -- for example a @"count"@ to control the number of results per page might default to @100@
513 -- if not supplied by the client in the request.
514 -- (Note: "default" has no meaning for required parameters.)
515 -- Unlike JSON Schema this value MUST conform to the defined type for this parameter.
516 _paramSchemaDefault :: Maybe Value
518 , _paramSchemaType :: SwaggerType t
519 , _paramSchemaFormat :: Maybe Format
520 , _paramSchemaItems :: Maybe (SwaggerItems t)
521 , _paramSchemaMaximum :: Maybe Scientific
522 , _paramSchemaExclusiveMaximum :: Maybe Bool
523 , _paramSchemaMinimum :: Maybe Scientific
524 , _paramSchemaExclusiveMinimum :: Maybe Bool
525 , _paramSchemaMaxLength :: Maybe Integer
526 , _paramSchemaMinLength :: Maybe Integer
527 , _paramSchemaPattern :: Maybe Pattern
528 , _paramSchemaMaxItems :: Maybe Integer
529 , _paramSchemaMinItems :: Maybe Integer
530 , _paramSchemaUniqueItems :: Maybe Bool
531 , _paramSchemaEnum :: Maybe [Value]
532 , _paramSchemaMultipleOf :: Maybe Scientific
533 } deriving (Eq, Show, Generic, Typeable)
535deriving instance (Data t, Data (SwaggerType t), Data (SwaggerItems t)) => Data (ParamSchema t)
537data Xml = Xml
538 { -- | Replaces the name of the element/attribute used for the described schema property.
539 -- When defined within the @'SwaggerItems'@ (items), it will affect the name of the individual XML elements within the list.
540 -- When defined alongside type being array (outside the items),
541 -- it will affect the wrapping element and only if wrapped is true.
542 -- If wrapped is false, it will be ignored.
543 _xmlName :: Maybe Text
545 -- | The URL of the namespace definition.
546 -- Value SHOULD be in the form of a URL.
547 , _xmlNamespace :: Maybe Text
549 -- | The prefix to be used for the name.
550 , _xmlPrefix :: Maybe Text
552 -- | Declares whether the property definition translates to an attribute instead of an element.
553 -- Default value is @False@.
554 , _xmlAttribute :: Maybe Bool
556 -- | MAY be used only for an array definition.
557 -- Signifies whether the array is wrapped
558 -- (for example, @\<books\>\<book/\>\<book/\>\</books\>@)
559 -- or unwrapped (@\<book/\>\<book/\>@).
560 -- Default value is @False@.
561 -- The definition takes effect only when defined alongside type being array (outside the items).
562 , _xmlWrapped :: Maybe Bool
563 } deriving (Eq, Show, Generic, Data, Typeable)
565-- | A container for the expected responses of an operation.
566-- The container maps a HTTP response code to the expected response.
567-- It is not expected from the documentation to necessarily cover all possible HTTP response codes,
568-- since they may not be known in advance.
569-- However, it is expected from the documentation to cover a successful operation response and any known errors.
570data Responses = Responses
571 { -- | The documentation of responses other than the ones declared for specific HTTP response codes.
572 -- It can be used to cover undeclared responses.
573 _responsesDefault :: Maybe (Referenced Response)
575 -- | Any HTTP status code can be used as the property name (one property per HTTP status code).
576 -- Describes the expected response for those HTTP status codes.
577 , _responsesResponses :: HashMap HttpStatusCode (Referenced Response)
578 } deriving (Eq, Show, Generic, Data, Typeable)
580type HttpStatusCode = Int
582-- | Describes a single response from an API Operation.
583data Response = Response
584 { -- | A short description of the response.
585 -- GFM syntax can be used for rich text representation.
586 _responseDescription :: Text
588 -- | A definition of the response structure.
589 -- It can be a primitive, an array or an object.
590 -- If this field does not exist, it means no content is returned as part of the response.
591 -- As an extension to the Schema Object, its root type value may also be "file".
592 -- This SHOULD be accompanied by a relevant produces mime-type.
593 , _responseSchema :: Maybe (Referenced Schema)
595 -- | A list of headers that are sent with the response.
596 , _responseHeaders :: HashMap HeaderName Header
598 -- | An example of the response message.
599 , _responseExamples :: Maybe Example
600 } deriving (Eq, Show, Generic, Data, Typeable)
602instance IsString Response where
603 fromString s = Response (fromString s) Nothing mempty Nothing
605type HeaderName = Text
607data Header = Header
608 { -- | A short description of the header.
609 _headerDescription :: Maybe Text
611 , _headerParamSchema :: ParamSchema Header
612 } deriving (Eq, Show, Generic, Data, Typeable)
614data Example = Example { getExample :: Map MediaType Value }
615 deriving (Eq, Show, Generic, Typeable)
617exampleConstr :: Constr
618exampleConstr = mkConstr exampleDataType "Example" ["getExample"] Prefix
620exampleDataType :: DataType
621exampleDataType = mkDataType "Data.Swagger.Example" [exampleConstr]
623instance Data Example where
624 gunfold k z c = case constrIndex c of
625 1 -> k (z (\m -> Example (Map.mapKeys fromString m)))
626 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type Example."
627 toConstr (Example _) = exampleConstr
628 dataTypeOf _ = exampleDataType
630-- | The location of the API key.
631data ApiKeyLocation
632 = ApiKeyQuery
633 | ApiKeyHeader
634 deriving (Eq, Show, Generic, Data, Typeable)
636data ApiKeyParams = ApiKeyParams
637 { -- | The name of the header or query parameter to be used.
638 _apiKeyName :: Text
640 -- | The location of the API key.
641 , _apiKeyIn :: ApiKeyLocation
642 } deriving (Eq, Show, Generic, Data, Typeable)
644-- | The authorization URL to be used for OAuth2 flow. This SHOULD be in the form of a URL.
645type AuthorizationURL = Text
647-- | The token URL to be used for OAuth2 flow. This SHOULD be in the form of a URL.
648type TokenURL = Text
650data OAuth2Flow
651 = OAuth2Implicit AuthorizationURL
652 | OAuth2Password TokenURL
653 | OAuth2Application TokenURL
654 | OAuth2AccessCode AuthorizationURL TokenURL
655 deriving (Eq, Show, Generic, Data, Typeable)
657data OAuth2Params = OAuth2Params
658 { -- | The flow used by the OAuth2 security scheme.
659 _oauth2Flow :: OAuth2Flow
661 -- | The available scopes for the OAuth2 security scheme.
662 , _oauth2Scopes :: HashMap Text Text
663 } deriving (Eq, Show, Generic, Data, Typeable)
665data SecuritySchemeType
666 = SecuritySchemeBasic
667 | SecuritySchemeApiKey ApiKeyParams
668 | SecuritySchemeOAuth2 OAuth2Params
669 deriving (Eq, Show, Generic, Data, Typeable)
671data SecurityScheme = SecurityScheme
672 { -- | The type of the security scheme.
673 _securitySchemeType :: SecuritySchemeType
675 -- | A short description for security scheme.
676 , _securitySchemeDescription :: Maybe Text
677 } deriving (Eq, Show, Generic, Data, Typeable)
679-- | Lists the required security schemes to execute this operation.
680-- The object can have multiple security schemes declared in it which are all required
681-- (that is, there is a logical AND between the schemes).
682newtype SecurityRequirement = SecurityRequirement
683 { getSecurityRequirement :: HashMap Text [Text]
684 } deriving (Eq, Read, Show, Monoid, ToJSON, FromJSON, Data, Typeable)
686-- | Tag name.
687type TagName = Text
689-- | Allows adding meta data to a single tag that is used by @Operation@.
690-- It is not mandatory to have a @Tag@ per tag used there.
691data Tag = Tag
692 { -- | The name of the tag.
693 _tagName :: TagName
695 -- | A short description for the tag.
696 -- GFM syntax can be used for rich text representation.
697 , _tagDescription :: Maybe Text
699 -- | Additional external documentation for this tag.
700 , _tagExternalDocs :: Maybe ExternalDocs
701 } deriving (Eq, Ord, Show, Generic, Data, Typeable)
703instance IsString Tag where
704 fromString s = Tag (fromString s) Nothing Nothing
706-- | Allows referencing an external resource for extended documentation.
707data ExternalDocs = ExternalDocs
708 { -- | A short description of the target documentation.
709 -- GFM syntax can be used for rich text representation.
710 _externalDocsDescription :: Maybe Text
712 -- | The URL for the target documentation.
713 , _externalDocsUrl :: URL
714 } deriving (Eq, Ord, Show, Generic, Data, Typeable)
716-- | A simple object to allow referencing other definitions in the specification.
717-- It can be used to reference parameters and responses that are defined at the top level for reuse.
718newtype Reference = Reference { getReference :: Text }
719 deriving (Eq, Show, Data, Typeable)
721data Referenced a
722 = Ref Reference
723 | Inline a
724 deriving (Eq, Show, Functor, Data, Typeable)
726instance IsString a => IsString (Referenced a) where
727 fromString = Inline . fromString
729newtype URL = URL { getUrl :: Text } deriving (Eq, Ord, Show, ToJSON, FromJSON, Data, Typeable)
731-- =======================================================================
732-- Monoid instances
733-- =======================================================================
735instance Monoid Swagger where
736 mempty = genericMempty
737 mappend = genericMappend
739instance Monoid Info where
740 mempty = genericMempty
741 mappend = genericMappend
743instance Monoid Contact where
744 mempty = genericMempty
745 mappend = genericMappend
747instance Monoid PathItem where
748 mempty = genericMempty
749 mappend = genericMappend
751instance Monoid Schema where
752 mempty = genericMempty
753 mappend = genericMappend
755instance Monoid (ParamSchema t) where
756 mempty = genericMempty
757 mappend = genericMappend
759instance Monoid Param where
760 mempty = genericMempty
761 mappend = genericMappend
763instance Monoid ParamOtherSchema where
764 mempty = genericMempty
765 mappend = genericMappend
767instance Monoid Header where
768 mempty = genericMempty
769 mappend = genericMappend
771instance Monoid Responses where
772 mempty = genericMempty
773 mappend = genericMappend
775instance Monoid Response where
776 mempty = genericMempty
777 mappend = genericMappend
779instance Monoid ExternalDocs where
780 mempty = genericMempty
781 mappend = genericMappend
783instance Monoid Operation where
784 mempty = genericMempty
785 mappend = genericMappend
787instance Monoid Example where
788 mempty = genericMempty
789 mappend = genericMappend
791-- =======================================================================
792-- SwaggerMonoid helper instances
793-- =======================================================================
795instance SwaggerMonoid Info
796instance SwaggerMonoid PathItem
797instance SwaggerMonoid Schema
798instance SwaggerMonoid (ParamSchema t)
799instance SwaggerMonoid Param
800instance SwaggerMonoid ParamOtherSchema
801instance SwaggerMonoid Responses
802instance SwaggerMonoid Response
803instance SwaggerMonoid ExternalDocs
804instance SwaggerMonoid Operation
806instance SwaggerMonoid MimeList
807deriving instance SwaggerMonoid URL
809instance SwaggerMonoid (SwaggerType t) where
810 swaggerMempty = SwaggerString
811 swaggerMappend _ y = y
813instance SwaggerMonoid ParamLocation where
814 swaggerMempty = ParamQuery
815 swaggerMappend _ y = y
817instance OVERLAPPING_ SwaggerMonoid (HashMap FilePath PathItem) where
818 swaggerMempty = HashMap.empty
819 swaggerMappend = HashMap.unionWith mappend
821instance Monoid a => SwaggerMonoid (Referenced a) where
822 swaggerMempty = Inline mempty
823 swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
824 swaggerMappend _ y = y
826instance SwaggerMonoid ParamAnySchema where
827 swaggerMempty = ParamOther swaggerMempty
828 swaggerMappend (ParamBody x) (ParamBody y) = ParamBody (swaggerMappend x y)
829 swaggerMappend (ParamOther x) (ParamOther y) = ParamOther (swaggerMappend x y)
830 swaggerMappend _ y = y
832-- =======================================================================
833-- Simple Generic-based ToJSON instances
834-- =======================================================================
836instance ToJSON ParamLocation where
837 toJSON = genericToJSON (jsonPrefix "Param")
839instance ToJSON Info where
840 toJSON = genericToJSON (jsonPrefix "Info")
842instance ToJSON Contact where
843 toJSON = genericToJSON (jsonPrefix "Contact")
845instance ToJSON License where
846 toJSON = genericToJSON (jsonPrefix "License")
848instance ToJSON ApiKeyLocation where
849 toJSON = genericToJSON (jsonPrefix "ApiKey")
851instance ToJSON ApiKeyParams where
852 toJSON = genericToJSON (jsonPrefix "apiKey")
854instance ToJSON Scheme where
855 toJSON = genericToJSON (jsonPrefix "")
857instance ToJSON Tag where
858 toJSON = genericToJSON (jsonPrefix "Tag")
860instance ToJSON ExternalDocs where
861 toJSON = genericToJSON (jsonPrefix "ExternalDocs")
863instance ToJSON Xml where
864 toJSON = genericToJSON (jsonPrefix "Xml")
866-- =======================================================================
867-- Simple Generic-based FromJSON instances
868-- =======================================================================
870instance FromJSON ParamLocation where
871 parseJSON = genericParseJSON (jsonPrefix "Param")
873instance FromJSON Info where
874 parseJSON = genericParseJSON (jsonPrefix "Info")
876instance FromJSON Contact where
877 parseJSON = genericParseJSON (jsonPrefix "Contact")
879instance FromJSON License where
880 parseJSON = genericParseJSON (jsonPrefix "License")
882instance FromJSON ApiKeyLocation where
883 parseJSON = genericParseJSON (jsonPrefix "ApiKey")
885instance FromJSON ApiKeyParams where
886 parseJSON = genericParseJSON (jsonPrefix "apiKey")
888instance FromJSON Scheme where
889 parseJSON = genericParseJSON (jsonPrefix "")
891instance FromJSON Tag where
892 parseJSON = genericParseJSON (jsonPrefix "Tag")
894instance FromJSON ExternalDocs where
895 parseJSON = genericParseJSON (jsonPrefix "ExternalDocs")
897-- =======================================================================
898-- Manual ToJSON instances
899-- =======================================================================
901instance ToJSON OAuth2Flow where
902 toJSON (OAuth2Implicit authUrl) = object
903 [ "flow" .= ("implicit" :: Text)
904 , "authorizationUrl" .= authUrl ]
905 toJSON (OAuth2Password tokenUrl) = object
906 [ "flow" .= ("password" :: Text)
907 , "tokenUrl" .= tokenUrl ]
908 toJSON (OAuth2Application tokenUrl) = object
909 [ "flow" .= ("application" :: Text)
910 , "tokenUrl" .= tokenUrl ]
911 toJSON (OAuth2AccessCode authUrl tokenUrl) = object
912 [ "flow" .= ("accessCode" :: Text)
913 , "authorizationUrl" .= authUrl
914 , "tokenUrl" .= tokenUrl ]
916instance ToJSON OAuth2Params where
917 toJSON = omitEmpties . genericToJSONWithSub "flow" (jsonPrefix "oauth2")
919instance ToJSON SecuritySchemeType where
920 toJSON SecuritySchemeBasic
921 = object [ "type" .= ("basic" :: Text) ]
922 toJSON (SecuritySchemeApiKey params)
923 = toJSON params
924 <+> object [ "type" .= ("apiKey" :: Text) ]
925 toJSON (SecuritySchemeOAuth2 params)
926 = toJSON params
927 <+> object [ "type" .= ("oauth2" :: Text) ]
929instance ToJSON Swagger where
930 toJSON = omitEmpties . addVersion . genericToJSON (jsonPrefix "swagger")
931 where
932 addVersion (Object o) = Object (HashMap.insert "swagger" "2.0" o)
933 addVersion _ = error "impossible"
935instance ToJSON SecurityScheme where
936 toJSON = genericToJSONWithSub "type" (jsonPrefix "securityScheme")
938instance ToJSON Schema where
939 toJSON = omitEmptiesExcept f . genericToJSONWithSub "paramSchema" (jsonPrefix "schema")
940 where
941 f "items" (Array _) = True
942 f _ _ = False
944instance ToJSON Header where
945 toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "header")
947instance ToJSON (SwaggerItems t) where
948 toJSON (SwaggerItemsPrimitive fmt schema) = object
949 [ "collectionFormat" .= fmt
950 , "items" .= schema ]
951 toJSON (SwaggerItemsObject x) = object [ "items" .= x ]
952 toJSON (SwaggerItemsArray x) = object [ "items" .= x ]
954instance ToJSON Host where
955 toJSON (Host host mport) = toJSON $
956 case mport of
957 Nothing -> host
958 Just port -> host ++ ":" ++ show port
960instance ToJSON MimeList where
961 toJSON (MimeList xs) = toJSON (map show xs)
963instance ToJSON Param where
964 toJSON = genericToJSONWithSub "schema" (jsonPrefix "param")
966instance ToJSON ParamAnySchema where
967 toJSON (ParamBody s) = object [ "in" .= ("body" :: Text), "schema" .= s ]
968 toJSON (ParamOther s) = toJSON s
970instance ToJSON ParamOtherSchema where
971 toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "paramOtherSchema")
973instance ToJSON Responses where
974 toJSON (Responses def rs) = omitEmpties $
975 toJSON (hashMapMapKeys show rs) <+> object [ "default" .= def ]
977instance ToJSON Response where
978 toJSON = omitEmpties . genericToJSON (jsonPrefix "response")
980instance ToJSON Operation where
981 toJSON = omitEmpties . genericToJSON (jsonPrefix "operation")
983instance ToJSON PathItem where
984 toJSON = omitEmpties . genericToJSON (jsonPrefix "pathItem")
986instance ToJSON Example where
987 toJSON = toJSON . Map.mapKeys show . getExample
989instance ToJSON Reference where
990 toJSON (Reference ref) = object [ "$ref" .= ref ]
992referencedToJSON :: ToJSON a => Text -> Referenced a -> Value
993referencedToJSON prefix (Ref (Reference ref)) = object [ "$ref" .= (prefix <> ref) ]
994referencedToJSON _ (Inline x) = toJSON x
996instance ToJSON (Referenced Schema) where toJSON = referencedToJSON "#/definitions/"
997instance ToJSON (Referenced Param) where toJSON = referencedToJSON "#/parameters/"
998instance ToJSON (Referenced Response) where toJSON = referencedToJSON "#/responses/"
1000instance ToJSON (SwaggerType t) where
1001 toJSON SwaggerArray = "array"
1002 toJSON SwaggerString = "string"
1003 toJSON SwaggerInteger = "integer"
1004 toJSON SwaggerNumber = "number"
1005 toJSON SwaggerBoolean = "boolean"
1006 toJSON SwaggerFile = "file"
1007 toJSON SwaggerNull = "null"
1008 toJSON SwaggerObject = "object"
1010instance ToJSON (CollectionFormat t) where
1011 toJSON CollectionCSV = "csv"
1012 toJSON CollectionSSV = "ssv"
1013 toJSON CollectionTSV = "tsv"
1014 toJSON CollectionPipes = "pipes"
1015 toJSON CollectionMulti = "multi"
1017instance ToJSON (ParamSchema t) where
1018 toJSON = omitEmptiesExcept f . genericToJSONWithSub "items" (jsonPrefix "paramSchema")
1019 where
1020 f "items" (Array _) = True
1021 f _ _ = False
1023-- =======================================================================
1024-- Manual FromJSON instances
1025-- =======================================================================
1027instance FromJSON OAuth2Flow where
1028 parseJSON (Object o) = do
1029 (flow :: Text) <- o .: "flow"
1030 case flow of
1031 "implicit" -> OAuth2Implicit <$> o .: "authorizationUrl"
1032 "password" -> OAuth2Password <$> o .: "tokenUrl"
1033 "application" -> OAuth2Application <$> o .: "tokenUrl"
1034 "accessCode" -> OAuth2AccessCode
1035 <$> o .: "authorizationUrl"
1036 <*> o .: "tokenUrl"
1037 _ -> empty
1038 parseJSON _ = empty
1040instance FromJSON OAuth2Params where
1041 parseJSON = genericParseJSONWithSub "flow" (jsonPrefix "oauth2")
1043instance FromJSON SecuritySchemeType where
1044 parseJSON js@(Object o) = do
1045 (t :: Text) <- o .: "type"
1046 case t of
1047 "basic" -> pure SecuritySchemeBasic
1048 "apiKey" -> SecuritySchemeApiKey <$> parseJSON js
1049 "oauth2" -> SecuritySchemeOAuth2 <$> parseJSON js
1050 _ -> empty
1051 parseJSON _ = empty
1053instance FromJSON Swagger where
1054 parseJSON js@(Object o) = do
1055 (version :: Text) <- o .: "swagger"
1056 when (version /= "2.0") empty
1057 (genericParseJSON (jsonPrefix "swagger")
1058 `withDefaults` [ "consumes" .= (mempty :: MimeList)
1059 , "produces" .= (mempty :: MimeList)
1060 , "security" .= ([] :: [SecurityRequirement])
1061 , "tags" .= ([] :: [Tag])
1062 , "definitions" .= (mempty :: Definitions Schema)
1063 , "parameters" .= (mempty :: Definitions Param)
1064 , "responses" .= (mempty :: Definitions Response)
1065 , "securityDefinitions" .= (mempty :: Definitions SecurityScheme)
1066 ] ) js
1067 parseJSON _ = empty
1069instance FromJSON SecurityScheme where
1070 parseJSON = genericParseJSONWithSub "type" (jsonPrefix "securityScheme")
1072instance FromJSON Schema where
1073 parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "schema")
1074 `withDefaults` [ "properties" .= (mempty :: HashMap Text Schema)
1075 , "required" .= ([] :: [ParamName]) ]
1077instance FromJSON Header where
1078 parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "header")
1080instance OVERLAPPABLE_ (FromJSON (CollectionFormat t), FromJSON (ParamSchema t)) => FromJSON (SwaggerItems t) where
1081 parseJSON = withObject "SwaggerItemsPrimitive" $ \o -> SwaggerItemsPrimitive
1082 <$> o .:? "collectionFormat"
1083 <*> (o .: "items" >>= parseJSON)
1085instance OVERLAPPABLE_ FromJSON (SwaggerItems Schema) where
1086 parseJSON js@(Object _) = SwaggerItemsObject <$> parseJSON js
1087 parseJSON js@(Array _) = SwaggerItemsArray <$> parseJSON js
1088 parseJSON _ = empty
1090instance FromJSON Host where
1091 parseJSON (String s) =
1092 case fromInteger <$> readMaybe portStr of
1093 Nothing | not (null portStr) -> fail $ "Invalid port `" ++ portStr ++ "'"
1094 mport -> pure $ Host host mport
1095 where
1096 (hostText, portText) = Text.breakOn ":" s
1097 [host, portStr] = map Text.unpack [hostText, portText]
1098 parseJSON _ = empty
1100instance FromJSON MimeList where
1101 parseJSON js = (MimeList . map fromString) <$> parseJSON js
1103instance FromJSON Param where
1104 parseJSON = genericParseJSONWithSub "schema" (jsonPrefix "param")
1106instance FromJSON ParamAnySchema where
1107 parseJSON js@(Object o) = do
1108 (i :: Text) <- o .: "in"
1109 case i of
1110 "body" -> do
1111 schema <- o .: "schema"
1112 ParamBody <$> parseJSON schema
1113 _ -> ParamOther <$> parseJSON js
1114 parseJSON _ = empty
1116instance FromJSON ParamOtherSchema where
1117 parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "paramOtherSchema")
1119instance FromJSON Responses where
1120 parseJSON (Object o) = Responses
1121 <$> o .:? "default"
1122 <*> (parseJSON (Object (HashMap.delete "default" o)) >>= hashMapReadKeys)
1123 parseJSON _ = empty
1125instance FromJSON Example where
1126 parseJSON js = do
1127 m <- parseJSON js
1128 pure $ Example (Map.mapKeys fromString m)
1130instance FromJSON Response where
1131 parseJSON = genericParseJSON (jsonPrefix "response")
1132 `withDefaults` [ "headers" .= (mempty :: HashMap HeaderName Header) ]
1134instance FromJSON Operation where
1135 parseJSON = genericParseJSON (jsonPrefix "operation")
1136 `withDefaults` [ "security" .= ([] :: [SecurityRequirement])
1137 , "tags" .= ([] :: [Tag])
1138 , "parameters" .= ([] :: [Referenced Param]) ]
1140instance FromJSON PathItem where
1141 parseJSON = genericParseJSON (jsonPrefix "pathItem")
1142 `withDefaults` [ "parameters" .= ([] :: [Param]) ]
1144instance FromJSON Reference where
1145 parseJSON (Object o) = Reference <$> o .: "$ref"
1146 parseJSON _ = empty
1148referencedParseJSON :: FromJSON a => Text -> Value -> JSON.Parser (Referenced a)
1149referencedParseJSON prefix js@(Object o) = do
1150 ms <- o .:? "$ref"
1151 case ms of
1152 Nothing -> Inline <$> parseJSON js
1153 Just s -> Ref <$> parseRef s
1154 where
1155 parseRef s = do
1156 case Text.stripPrefix prefix s of
1157 Nothing -> fail $ "expected $ref of the form \"" <> Text.unpack prefix <> "*\", but got " <> show s
1158 Just suffix -> pure (Reference suffix)
1159referencedParseJSON _ _ = fail "referenceParseJSON: not an object"
1161instance FromJSON (Referenced Schema) where parseJSON = referencedParseJSON "#/definitions/"
1162instance FromJSON (Referenced Param) where parseJSON = referencedParseJSON "#/parameters/"
1163instance FromJSON (Referenced Response) where parseJSON = referencedParseJSON "#/responses/"
1165instance FromJSON Xml where
1166 parseJSON = genericParseJSON (jsonPrefix "xml")
1168instance FromJSON (SwaggerType Schema) where
1169 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray, SwaggerNull, SwaggerObject]
1171instance FromJSON (SwaggerType ParamOtherSchema) where
1172 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray, SwaggerFile]
1174instance OVERLAPPABLE_ FromJSON (SwaggerType t) where
1175 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray]
1177instance OVERLAPPABLE_ FromJSON (CollectionFormat t) where
1178 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
1180instance FromJSON (CollectionFormat ParamOtherSchema) where
1181 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
1183-- NOTE: The constraints @FromJSON (SwaggerType t)@ and
1184-- @FromJSON (SwaggerItems t)@ are necessary here!
1185-- Without the constraint the general instance will be used
1186-- that only accepts common types (i.e. NOT object, null or file)
1187-- and primitive array items.
1188instance (FromJSON (SwaggerType t), FromJSON (SwaggerItems t)) => FromJSON (ParamSchema t) where
1189 parseJSON = genericParseJSONWithSub "items" (jsonPrefix "ParamSchema")