@@ -211,7 +211,7 @@ data PathItem = PathItem
211211data Operation = Operation
212212 { -- | A list of tags for API documentation control.
213213 -- Tags can be used for logical grouping of operations by resources or any other qualifier.
214− _operationTags :: [Text]
214+ _operationTags :: [TagName]
215215
216216 -- | A short summary of what the operation does.
217217 -- For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
@@ -319,15 +319,21 @@ data ParamOtherSchema = ParamOtherSchema
319319 -- Default value is @False@.
320320 , _paramOtherSchemaAllowEmptyValue :: Maybe Bool
321321
322− -- | Determines the format of the array if @'ParamArray'@ is used.
323− -- Default value is csv.
324− , _paramOtherSchemaCollectionFormat :: Maybe (CollectionFormat Param)
325−
326322 , _paramOtherSchemaParamSchema :: ParamSchema ParamOtherSchema
327323 } deriving (Eq, Show, Generic, Data, Typeable)
328324
325+-- | Items for @'SwaggerArray'@ schemas.
326+--
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>.
331+--
332+-- @'SwaggerItemsObject'@ should be used to specify homogenous array @'Schema'@s.
333+--
334+-- @'SwaggerItemsArray'@ should be used to specify tuple @'Schema'@s.
329335data SwaggerItems t where
330− SwaggerItemsPrimitive :: Items -> SwaggerItems t
336+ SwaggerItemsPrimitive :: Maybe (CollectionFormat t) -> ParamSchema t -> SwaggerItems t
331337 SwaggerItemsObject :: Referenced Schema -> SwaggerItems Schema
332338 SwaggerItemsArray :: [Referenced Schema] -> SwaggerItems Schema
333339
@@ -341,9 +347,9 @@ swaggerItemsPrimitiveConstr = mkConstr swaggerItemsDataType "SwaggerItemsPrimiti
341347swaggerItemsDataType :: DataType
342348swaggerItemsDataType = mkDataType "Data.Swagger.SwaggerItems" [swaggerItemsPrimitiveConstr]
343349
344−instance {-# OVERLAPPABLE #-} Typeable t => Data (SwaggerItems t) where
350+instance {-# OVERLAPPABLE #-} Data t => Data (SwaggerItems t) where
345351 gunfold k z c = case constrIndex c of
346− 1 -> k (z SwaggerItemsPrimitive)
352+ 1 -> k (k (z SwaggerItemsPrimitive))
347353 _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type (SwaggerItems t)."
348354 toConstr _ = swaggerItemsPrimitiveConstr
349355 dataTypeOf _ = swaggerItemsDataType
@@ -508,7 +514,7 @@ deriving instance (Data t, Data (SwaggerType t), Data (SwaggerItems t)) => Data
508514
509515data Xml = Xml
510516 { -- | 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.
512518 -- When defined alongside type being array (outside the items),
513519 -- it will affect the wrapping element and only if wrapped is true.
514520 -- If wrapped is false, it will be ignored.
@@ -534,14 +540,6 @@ data Xml = Xml
534540 , _xmlWrapped :: Maybe Bool
535541 } deriving (Eq, Show, Generic, Data, Typeable)
536542
537−data Items = Items
538− { -- | Determines the format of the array if type array is used.
539− -- Default value is @'ItemsCollectionCSV'@.
540− _itemsCollectionFormat :: Maybe (CollectionFormat Items)
541−
542− , _itemsParamSchema :: ParamSchema Items
543− } deriving (Eq, Show, Generic, Data, Typeable)
544−
545543-- | A container for the expected responses of an operation.
546544-- The container maps a HTTP response code to the expected response.
547545-- It is not expected from the documentation to necessarily cover all possible HTTP response codes,
@@ -585,10 +583,6 @@ data Header = Header
585583 { -- | A short description of the header.
586584 _headerDescription :: Maybe Text
587585
588− -- | Determines the format of the array if type array is used.
589− -- Default value is @'ItemsCollectionCSV'@.
590− , _headerCollectionFormat :: Maybe (CollectionFormat Items)
591−
592586 , _headerParamSchema :: ParamSchema Header
593587 } deriving (Eq, Show, Generic, Data, Typeable)
594588
@@ -664,11 +658,14 @@ newtype SecurityRequirement = SecurityRequirement
664658 { getSecurityRequirement :: HashMap Text [Text]
665659 } deriving (Eq, Read, Show, Monoid, ToJSON, FromJSON, Data, Typeable)
666660
661+-- | Tag name.
662+type TagName = Text
663+
667664-- | Allows adding meta data to a single tag that is used by @Operation@.
668665-- It is not mandatory to have a @Tag@ per tag used there.
669666data Tag = Tag
670667 { -- | The name of the tag.
671− _tagName :: Text
668+ _tagName :: TagName
672669
673670 -- | A short description for the tag.
674671 -- GFM syntax can be used for rich text representation.
@@ -736,6 +733,10 @@ instance Monoid ParamOtherSchema where
736733 mempty = genericMempty
737734 mappend = genericMappend
738735
736+instance Monoid Header where
737+ mempty = genericMempty
738+ mappend = genericMappend
739+
739740instance Monoid Responses where
740741 mempty = genericMempty
741742 mappend = genericMappend
@@ -752,6 +753,10 @@ instance Monoid Operation where
752753 mempty = genericMempty
753754 mappend = genericMappend
754755
756+instance Monoid Example where
757+ mempty = genericMempty
758+ mappend = genericMappend
759+
755760-- =======================================================================
756761-- SwaggerMonoid helper instances
757762-- =======================================================================
@@ -779,43 +784,15 @@ instance SwaggerMonoid ParamLocation where
779784 swaggerMempty = ParamQuery
780785 swaggerMappend _ y = y
781786
782−instance SwaggerMonoid (HashMap Text Schema) where
787+instance SwaggerMonoid (HashMap FilePath PathItem) where
783788 swaggerMempty = HashMap.empty
784789 swaggerMappend = HashMap.unionWith mappend
785790
786−instance SwaggerMonoid (HashMap Text (Referenced Schema)) where
787− swaggerMempty = HashMap.empty
788− swaggerMappend = HashMap.unionWith swaggerMappend
789−
790791instance Monoid a => SwaggerMonoid (Referenced a) where
791792 swaggerMempty = Inline mempty
792793 swaggerMappend (Inline x) (Inline y) = Inline (x <> y)
793794 swaggerMappend _ y = y
794795
795−instance SwaggerMonoid (HashMap Text Param) where
796− swaggerMempty = HashMap.empty
797− swaggerMappend = HashMap.unionWith mappend
798−
799−instance SwaggerMonoid (HashMap Text Response) where
800− swaggerMempty = HashMap.empty
801− swaggerMappend = flip HashMap.union
802−
803−instance SwaggerMonoid (HashMap Text SecurityScheme) where
804− swaggerMempty = HashMap.empty
805− swaggerMappend = flip HashMap.union
806−
807−instance SwaggerMonoid (HashMap FilePath PathItem) where
808− swaggerMempty = HashMap.empty
809− swaggerMappend = HashMap.unionWith mappend
810−
811−instance SwaggerMonoid (HashMap HeaderName Header) where
812− swaggerMempty = HashMap.empty
813− swaggerMappend = flip HashMap.union
814−
815−instance SwaggerMonoid (HashMap HttpStatusCode (Referenced Response)) where
816− swaggerMempty = HashMap.empty
817− swaggerMappend = flip HashMap.union
818−
819796instance SwaggerMonoid ParamAnySchema where
820797 swaggerMempty = ParamOther swaggerMempty
821798 swaggerMappend (ParamBody x) (ParamBody y) = ParamBody (swaggerMappend x y)
@@ -934,13 +911,12 @@ instance ToJSON Schema where
934911instance ToJSON Header where
935912 toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "header")
936913
937−instance ToJSON Items where
938− toJSON = genericToJSONWithSub "paramSchema" (jsonPrefix "items")
939−
940914instance ToJSON (SwaggerItems t) where
941− toJSON (SwaggerItemsPrimitive x) = toJSON x
942− toJSON (SwaggerItemsObject x) = toJSON x
943− toJSON (SwaggerItemsArray x) = toJSON x
915+ toJSON (SwaggerItemsPrimitive fmt schema) = object
916+ [ "collectionFormat" .= fmt
917+ , "items" .= schema ]
918+ toJSON (SwaggerItemsObject x) = object [ "items" .= x ]
919+ toJSON (SwaggerItemsArray x) = object [ "items" .= x ]
944920
945921instance ToJSON Host where
946922 toJSON (Host host mport) = toJSON $
@@ -1009,7 +985,7 @@ instance ToJSON (CollectionFormat t) where
1009985 toJSON CollectionMulti = "multi"
1010986
1011987instance ToJSON (ParamSchema t) where
1012− toJSON = genericToJSON (jsonPrefix "paramSchema")
988+ toJSON = omitEmpties . genericToJSONWithSub "items" (jsonPrefix "paramSchema")
1013989
1014990-- =======================================================================
1015991-- Manual FromJSON instances
@@ -1068,11 +1044,10 @@ instance FromJSON Schema where
10681044instance FromJSON Header where
10691045 parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "header")
10701046
1071−instance FromJSON Items where
1072− parseJSON = genericParseJSONWithSub "paramSchema" (jsonPrefix "items")
1073−
1074−instance {-# OVERLAPPABLE #-} FromJSON (SwaggerItems t) where
1075− parseJSON js = SwaggerItemsPrimitive <$> parseJSON js
1047+instance {-# OVERLAPPABLE #-} (FromJSON (CollectionFormat t), FromJSON (ParamSchema t)) => FromJSON (SwaggerItems t) where
1048+ parseJSON (Object o) = SwaggerItemsPrimitive
1049+ <$> o .:? "collectionFormat"
1050+ <*> (o .: "items" >>= parseJSON)
10761051
10771052instance {-# OVERLAPPING #-} FromJSON (SwaggerItems Schema) where
10781053 parseJSON js@(Object _) = SwaggerItemsObject <$> parseJSON js
@@ -1166,16 +1141,17 @@ instance FromJSON (SwaggerType ParamOtherSchema) where
11661141instance {-# OVERLAPPABLE #-} FromJSON (SwaggerType t) where
11671142 parseJSON = parseOneOf [SwaggerString, SwaggerInteger, SwaggerNumber, SwaggerBoolean, SwaggerArray]
11681143
1144+instance {-# OVERLAPPABLE #-} FromJSON (CollectionFormat t) where
1145+ parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
1146+
11691147instance FromJSON (CollectionFormat Param) where
11701148 parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes, CollectionMulti]
11711149
1172−instance FromJSON (CollectionFormat Items) where
1173− parseJSON = parseOneOf [CollectionCSV, CollectionSSV, CollectionTSV, CollectionPipes]
1174−
11751150-- NOTE: The constraints @FromJSON (SwaggerType t)@ and
11761151-- @FromJSON (SwaggerItems t)@ are necessary here!
11771152-- Without the constraint the general instance will be used
11781153-- that only accepts common types (i.e. NOT object, null or file)
11791154-- and primitive array items.
11801155instance (FromJSON (SwaggerType t), FromJSON (SwaggerItems t)) => FromJSON (ParamSchema t) where
1181− parseJSON = genericParseJSON (jsonPrefix "ParamSchema")
1156+ parseJSON = genericParseJSONWithSub "items" (jsonPrefix "ParamSchema")
1157+