@@ -211,7 +211,7 @@ data PathItem = PathItem
211data Operation = Operation
211data Operation = Operation
212 { -- | A list of tags for API documentation control.
212 { -- | A list of tags for API documentation control.
213 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
213 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
214− _operationTags :: [Text]
214+ _operationTags :: [TagName]
216 -- | A short summary of what the operation does.
216 -- | A short summary of what the operation does.
217 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
217 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
@@ -319,15 +319,21 @@ data ParamOtherSchema = ParamOtherSchema
319 -- Default value is @False@.
319 -- Default value is @False@.
320 , _paramOtherSchemaAllowEmptyValue :: Maybe Bool
320 , _paramOtherSchemaAllowEmptyValue :: Maybe Bool
322− -- | Determines the format of the array if @'ParamArray'@ is used.
323− -- Default value is csv.
324− , _paramOtherSchemaCollectionFormat :: Maybe (CollectionFormat Param)
326 , _paramOtherSchemaParamSchema :: ParamSchema ParamOtherSchema
322 , _paramOtherSchemaParamSchema :: ParamSchema ParamOtherSchema
327 } deriving (Eq, Show, Generic, Data, Typeable)
323 } deriving (Eq, Show, Generic, Data, Typeable)
325+-- | Items for @'SwaggerArray'@ schemas.
327+-- @'SwaggerItemsPrimitive'@ should be used only for query params, headers and path pieces.
328+-- The @'CollectionFormat' t@ parameter specifies how elements of an array should be displayed.
329+-- Note that @fmt@ in @'SwaggerItemsPrimitive' fmt schema@ specifies format for elements of type @schema@.
330+-- This is different from the original Swagger's <http://swagger.io/specification/#itemsObject Items Object>.
332+-- @'SwaggerItemsObject'@ should be used to specify homogenous array @'Schema'@s.
334+-- @'SwaggerItemsArray'@ should be used to specify tuple @'Schema'@s.
329data SwaggerItems t where
335data SwaggerItems t where
330− SwaggerItemsPrimitive :: Items -> SwaggerItems t
336+ SwaggerItemsPrimitive :: Maybe (CollectionFormat t) -> ParamSchema t -> SwaggerItems t
331 SwaggerItemsObject :: Referenced Schema -> SwaggerItems Schema
337 SwaggerItemsObject :: Referenced Schema -> SwaggerItems Schema
332 SwaggerItemsArray :: [Referenced Schema] -> SwaggerItems Schema
338 SwaggerItemsArray :: [Referenced Schema] -> SwaggerItems Schema
@@ -341,9 +347,9 @@ swaggerItemsPrimitiveConstr = mkConstr swaggerItemsDataType "SwaggerItemsPrimiti
341swaggerItemsDataType :: DataType
347swaggerItemsDataType :: DataType
342swaggerItemsDataType = mkDataType "Data.Swagger.SwaggerItems" [swaggerItemsPrimitiveConstr]
348swaggerItemsDataType = mkDataType "Data.Swagger.SwaggerItems" [swaggerItemsPrimitiveConstr]
344−instance {-# OVERLAPPABLE #-} Typeable t => Data (SwaggerItems t) where
350+instance {-# OVERLAPPABLE #-} Data t => Data (SwaggerItems t) where
345 gunfold k z c = case constrIndex c of
351 gunfold k z c = case constrIndex c of
346− 1 -> k (z SwaggerItemsPrimitive)
352+ 1 -> k (k (z SwaggerItemsPrimitive))
347 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems t)."
353 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems t)."
348 toConstr _ = swaggerItemsPrimitiveConstr
354 toConstr _ = swaggerItemsPrimitiveConstr
349 dataTypeOf _ = swaggerItemsDataType
355 dataTypeOf _ = swaggerItemsDataType
@@ -508,7 +514,7 @@ deriving instance (Data t, Data (SwaggerType t), Data (SwaggerItems t)) => Data
509data Xml = Xml
515data Xml = Xml
510 { -- | Replaces the name of the element/attribute used for the described schema property.
516 { -- | Replaces the name of the element/attribute used for the described schema property.
511− -- When defined within the @'Items'@ (items), it will affect the name of the individual XML elements within the list.
517+ -- When defined within the @'SwaggerItems'@ (items), it will affect the name of the individual XML elements within the list.
512 -- When defined alongside type being array (outside the items),
518 -- When defined alongside type being array (outside the items),
513 -- it will affect the wrapping element and only if wrapped is true.
519 -- it will affect the wrapping element and only if wrapped is true.
514 -- If wrapped is false, it will be ignored.
520 -- If wrapped is false, it will be ignored.
@@ -534,14 +540,6 @@ data Xml = Xml
534 , _xmlWrapped :: Maybe Bool
540 , _xmlWrapped :: Maybe Bool
535 } deriving (Eq, Show, Generic, Data, Typeable)
541 } deriving (Eq, Show, Generic, Data, Typeable)
538− { -- | Determines the format of the array if type array is used.
539− -- Default value is @'ItemsCollectionCSV'@.
540− _itemsCollectionFormat :: Maybe (CollectionFormat Items)
542− , _itemsParamSchema :: ParamSchema Items
543− } deriving (Eq, Show, Generic, Data, Typeable)
545-- | A container for the expected responses of an operation.
543-- | A container for the expected responses of an operation.
546-- The container maps a HTTP response code to the expected response.
544-- The container maps a HTTP response code to the expected response.
547-- It is not expected from the documentation to necessarily cover all possible HTTP response codes,
545-- It is not expected from the documentation to necessarily cover all possible HTTP response codes,
@@ -585,10 +583,6 @@ data Header = Header
585 { -- | A short description of the header.
583 { -- | A short description of the header.
586 _headerDescription :: Maybe Text
584 _headerDescription :: Maybe Text
588− -- | Determines the format of the array if type array is used.
589− -- Default value is @'ItemsCollectionCSV'@.
590− , _headerCollectionFormat :: Maybe (CollectionFormat Items)
592 , _headerParamSchema :: ParamSchema Header
586 , _headerParamSchema :: ParamSchema Header
593 } deriving (Eq, Show, Generic, Data, Typeable)
587 } deriving (Eq, Show, Generic, Data, Typeable)
@@ -664,11 +658,14 @@ newtype SecurityRequirement = SecurityRequirement
664 { getSecurityRequirement :: HashMap Text [Text]
658 { getSecurityRequirement :: HashMap Text [Text]
665 } deriving (Eq, Read, Show, Monoid, ToJSON, FromJSON, Data, Typeable)
659 } deriving (Eq, Read, Show, Monoid, ToJSON, FromJSON, Data, Typeable)
667-- | Allows adding meta data to a single tag that is used by @Operation@.
664-- | Allows adding meta data to a single tag that is used by @Operation@.
668-- It is not mandatory to have a @Tag@ per tag used there.
665-- It is not mandatory to have a @Tag@ per tag used there.
669data Tag = Tag
666data Tag = Tag
670 { -- | The name of the tag.
667 { -- | The name of the tag.
671− _tagName :: Text
668+ _tagName :: TagName
673 -- | A short description for the tag.
670 -- | A short description for the tag.
674 -- GFM syntax can be used for rich text representation.
671 -- GFM syntax can be used for rich text representation.
@@ -736,6 +733,10 @@ instance Monoid ParamOtherSchema where
736 mempty = genericMempty
733 mempty = genericMempty
737 mappend = genericMappend
734 mappend = genericMappend
736+instance Monoid Header where
737+ mempty = genericMempty
738+ mappend = genericMappend
739instance Monoid Responses where
740instance Monoid Responses where
740 mempty = genericMempty
741 mempty = genericMempty
741 mappend = genericMappend
742 mappend = genericMappend
@@ -752,6 +753,10 @@ instance Monoid Operation where
752 mempty = genericMempty
753 mempty = genericMempty
753 mappend = genericMappend
754 mappend = genericMappend
756+instance Monoid Example where
757+ mempty = genericMempty
758+ mappend = genericMappend
755-- =======================================================================
760-- =======================================================================
756-- SwaggerMonoid helper instances
761-- SwaggerMonoid helper instances
757-- =======================================================================
762-- =======================================================================
@@ -779,43 +784,15 @@ instance SwaggerMonoid ParamLocation where
779 swaggerMempty = ParamQuery
784 swaggerMempty = ParamQuery
780 swaggerMappend _ y = y
785 swaggerMappend _ y = y
782−instance SwaggerMonoid (HashMap Text Schema) where
787+instance SwaggerMonoid (HashMap FilePath PathItem) where
783 swaggerMempty = HashMap.empty
788 swaggerMempty = HashMap.empty
784 swaggerMappend = HashMap.unionWith mappend
789 swaggerMappend = HashMap.unionWith mappend
786−instance SwaggerMonoid (HashMap Text (Referenced Schema)) where
787− swaggerMempty = HashMap.empty
788− swaggerMappend = HashMap.unionWith swaggerMappend
790instance Monoid a => SwaggerMonoid (Referenced a) where
791instance Monoid a => SwaggerMonoid (Referenced a) where
791 swaggerMempty = Inline mempty
792 swaggerMempty = Inline mempty
792 swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
793 swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
793 swaggerMappend _ y = y
794 swaggerMappend _ y = y
795−instance SwaggerMonoid (HashMap Text Param) where
796− swaggerMempty = HashMap.empty
797− swaggerMappend = HashMap.unionWith mappend
799−instance SwaggerMonoid (HashMap Text Response) where
800− swaggerMempty = HashMap.empty
801− swaggerMappend = flip HashMap.union
803−instance SwaggerMonoid (HashMap Text SecurityScheme) where
804− swaggerMempty = HashMap.empty
805− swaggerMappend = flip HashMap.union
807−instance SwaggerMonoid (HashMap FilePath PathItem) where
808− swaggerMempty = HashMap.empty
809− swaggerMappend = HashMap.unionWith mappend
811−instance SwaggerMonoid (HashMap HeaderName Header) where
812− swaggerMempty = HashMap.empty
813− swaggerMappend = flip HashMap.union
815−instance SwaggerMonoid (HashMap HttpStatusCode (Referenced Response)) where
816− swaggerMempty = HashMap.empty
817− swaggerMappend = flip HashMap.union
819instance SwaggerMonoid ParamAnySchema where
796instance SwaggerMonoid ParamAnySchema where
820 swaggerMempty = ParamOther swaggerMempty
797 swaggerMempty = ParamOther swaggerMempty
821 swaggerMappend (ParamBody x) (ParamBody y) = ParamBody (swaggerMappend x y)
798 swaggerMappend (ParamBody x) (ParamBody y) = ParamBody (swaggerMappend x y)
@@ -934,13 +911,12 @@ instance ToJSON Schema where
934instance ToJSON Header where
911instance ToJSON Header where
935 toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "header")
912 toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "header")
937−instance ToJSON Items where
938− toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "items")
940instance ToJSON (SwaggerItems t) where
914instance ToJSON (SwaggerItems t) where
941− toJSON (SwaggerItemsPrimitive x) = toJSON x
915+ toJSON (SwaggerItemsPrimitive fmt schema) = object
916+ [ "collectionFormat" .= fmt
917+ , "items" .= schema ]
942− toJSON (SwaggerItemsObject x) = toJSON x
918+ toJSON (SwaggerItemsObject x) = object [ "items" .= x ]
943− toJSON (SwaggerItemsArray x) = toJSON x
919+ toJSON (SwaggerItemsArray x) = object [ "items" .= x ]
945instance ToJSON Host where
921instance ToJSON Host where
946 toJSON (Host host mport) = toJSON $
922 toJSON (Host host mport) = toJSON $
@@ -1009,7 +985,7 @@ instance ToJSON (CollectionFormat t) where
1009 toJSON CollectionMulti = "multi"
985 toJSON CollectionMulti = "multi"
1011instance ToJSON (ParamSchema t) where
987instance ToJSON (ParamSchema t) where
1012− toJSON = genericToJSON (jsonPrefix "paramSchema")
988+ toJSON = omitEmpties . genericToJSONWithSub "items" (jsonPrefix "paramSchema")
1014-- =======================================================================
990-- =======================================================================
1015-- Manual FromJSON instances
991-- Manual FromJSON instances
@@ -1068,11 +1044,10 @@ instance FromJSON Schema where
1068instance FromJSON Header where
1044instance FromJSON Header where
1069 parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "header")
1045 parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "header")
1071−instance FromJSON Items where
1072− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "items")
1074−instance {-# OVERLAPPABLE #-} FromJSON (SwaggerItems t) where
1047+instance {-# OVERLAPPABLE #-} (FromJSON (CollectionFormat t), FromJSON (ParamSchema t)) => FromJSON (SwaggerItems t) where
1075− parseJSON js = SwaggerItemsPrimitive <$> parseJSON js
1048+ parseJSON (Object o) = SwaggerItemsPrimitive
1049+ <$> o .:? "collectionFormat"
1050+ <*> (o .: "items" >>= parseJSON)
1077instance {-# OVERLAPPING #-} FromJSON (SwaggerItems Schema) where
1052instance {-# OVERLAPPING #-} FromJSON (SwaggerItems Schema) where
1078 parseJSON js@(Object _) = SwaggerItemsObject <$> parseJSON js
1053 parseJSON js@(Object _) = SwaggerItemsObject <$> parseJSON js
@@ -1166,16 +1141,17 @@ instance FromJSON (SwaggerType ParamOtherSchema) where
1166instance {-# OVERLAPPABLE #-} FromJSON (SwaggerType t) where
1141instance {-# OVERLAPPABLE #-} FromJSON (SwaggerType t) where
1167 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray]
1142 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray]
1144+instance {-# OVERLAPPABLE #-} FromJSON (CollectionFormat t) where
1145+ parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
1169instance FromJSON (CollectionFormat Param) where
1147instance FromJSON (CollectionFormat Param) where
1170 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
1148 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
1172−instance FromJSON (CollectionFormat Items) where
1173− parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
1175-- NOTE: The constraints @FromJSON (SwaggerType t)@ and
1150-- NOTE: The constraints @FromJSON (SwaggerType t)@ and
1176-- @FromJSON (SwaggerItems t)@ are necessary here!
1151-- @FromJSON (SwaggerItems t)@ are necessary here!
1177-- Without the constraint the general instance will be used
1152-- Without the constraint the general instance will be used
1178-- that only accepts common types (i.e. NOT object, null or file)
1153-- that only accepts common types (i.e. NOT object, null or file)
1179-- and primitive array items.
1154-- and primitive array items.
1180instance (FromJSON (SwaggerType t), FromJSON (SwaggerItems t)) => FromJSON (ParamSchema t) where
1155instance (FromJSON (SwaggerType t), FromJSON (SwaggerItems t)) => FromJSON (ParamSchema t) where
1181− parseJSON = genericParseJSON (jsonPrefix "ParamSchema")
1156+ parseJSON = genericParseJSONWithSub "items" (jsonPrefix "ParamSchema")