@@ -189,7 +189,7 @@ data SwaggerPathItem = SwaggerPathItem
189189 -- These parameters can be overridden at the operation level, but cannot be removed there.
190190 -- The list MUST NOT include duplicated parameters.
191191 -- A unique parameter is defined by a combination of a name and location.
192− , swaggerPathItemParameters :: [SwaggerParameter]
192+ , swaggerPathItemParameters :: [SwaggerReferenced SwaggerParameter]
193193 } deriving (Eq, Show, Generic)
194194
195195-- | Describes a single API operation on a path.
@@ -230,7 +230,7 @@ data SwaggerOperation = SwaggerOperation
230230 -- the new definition will override it, but can never remove it.
231231 -- The list MUST NOT include duplicated parameters.
232232 -- A unique parameter is defined by a combination of a name and location.
233− , swaggerOperationParameters :: [SwaggerParameter]
233+ , swaggerOperationParameters :: [SwaggerReferenced SwaggerParameter]
234234
235235 -- | The list of possible responses as they are returned from executing this operation.
236236 , swaggerOperationResponses :: SwaggerResponses
@@ -392,7 +392,7 @@ data SwaggerSchema = SwaggerSchema
392392
393393 , swaggerSchemaItems :: Maybe SwaggerSchemaItems
394394 , swaggerSchemaAllOf :: Maybe [SwaggerSchema]
395− , swaggerSchemaProperties :: HashMap Text SwaggerSchema
395+ , swaggerSchemaProperties :: HashMap Text (SwaggerReferenced SwaggerSchema)
396396 , swaggerSchemaAdditionalProperties :: Maybe SwaggerSchema
397397
398398 , swaggerSchemaDiscriminator :: Maybe Text
@@ -488,11 +488,11 @@ data SwaggerItems = SwaggerItems
488488data SwaggerResponses = SwaggerResponses
489489 { -- | The documentation of responses other than the ones declared for specific HTTP response codes.
490490 -- It can be used to cover undeclared responses.
491− swaggerResponsesDefault :: Maybe SwaggerResponse
491+ swaggerResponsesDefault :: Maybe (SwaggerReferenced SwaggerResponse)
492492
493493 -- | Any HTTP status code can be used as the property name (one property per HTTP status code).
494494 -- Describes the expected response for those HTTP status codes.
495− , swaggerResponsesResponses :: HashMap HttpStatusCode SwaggerResponse
495+ , swaggerResponsesResponses :: HashMap HttpStatusCode (SwaggerReferenced SwaggerResponse)
496496 } deriving (Eq, Show, Generic)
497497
498498type HttpStatusCode = Int
@@ -623,6 +623,16 @@ data SwaggerExternalDocs = SwaggerExternalDocs
623623 , swaggerExternalDocsUrl :: URL
624624 } deriving (Eq, Show, Generic)
625625
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.
628+newtype SwaggerReference = SwaggerReference { getSwaggerReference :: Text }
629+ deriving (Eq, Show)
630+
631+data SwaggerReferenced a
632+ = SwaggerRef SwaggerReference
633+ | SwaggerInline a
634+ deriving (Eq, Show)
635+
626636newtype URL = URL { getUrl :: Text } deriving (Eq, Show, ToJSON, FromJSON)
627637
628638-- =======================================================================
@@ -712,6 +722,13 @@ instance SwaggerMonoid (HashMap Text SwaggerSchema) where
712722 swaggerMempty = HashMap.empty
713723 swaggerMappend = HashMap.unionWith mappend
714724
725+instance SwaggerMonoid (HashMap Text (SwaggerReferenced SwaggerSchema)) where
726+ swaggerMempty = HashMap.empty
727+ swaggerMappend = HashMap.unionWith merge
728+ where
729+ merge (SwaggerInline x) (SwaggerInline y) = SwaggerInline (x <> y)
730+ merge _ y = y
731+
715732instance SwaggerMonoid (HashMap Text SwaggerParameter) where
716733 swaggerMempty = HashMap.empty
717734 swaggerMappend = HashMap.unionWith mappend
@@ -732,7 +749,7 @@ instance SwaggerMonoid (HashMap HeaderName SwaggerHeader) where
732749 swaggerMempty = HashMap.empty
733750 swaggerMappend = flip HashMap.union
734751
735−instance SwaggerMonoid (HashMap HttpStatusCode SwaggerResponse) where
752+instance SwaggerMonoid (HashMap HttpStatusCode (SwaggerReferenced SwaggerResponse)) where
736753 swaggerMempty = HashMap.empty
737754 swaggerMappend = flip HashMap.union
738755
@@ -849,6 +866,13 @@ instance ToJSON SwaggerResponses where
849866instance ToJSON SwaggerExample where
850867 toJSON = toJSON . Map.mapKeys show . getSwaggerExample
851868
869+instance ToJSON SwaggerReference where
870+ toJSON (SwaggerReference ref) = object [ "$ref" .= ref ]
871+
872+instance ToJSON a => ToJSON (SwaggerReferenced a) where
873+ toJSON (SwaggerRef ref) = toJSON ref
874+ toJSON (SwaggerInline x) = toJSON x
875+
852876-- =======================================================================
853877-- Manual FromJSON instances
854878-- =======================================================================
@@ -970,3 +994,12 @@ instance FromJSON SwaggerPathItem where
970994 parseJSON = genericParseJSON (jsonPrefix "swaggerPathItem")
971995 `withDefaults` [ "parameters" .= ([] :: [SwaggerParameter]) ]
972996
997+instance FromJSON SwaggerReference where
998+ parseJSON (Object o) = SwaggerReference <$> o .: "$ref"
999+ parseJSON _ = empty
1000+
1001+instance FromJSON a => FromJSON (SwaggerReferenced a) where
1002+ parseJSON json
1003+ = SwaggerRef <$> parseJSON json
1004+ <|> SwaggerInline <$> parseJSON json
1005+