5902310 · typeable/openapi3

git.iko.soy/typeable/openapi3

on master help sign in

Add Example

5902310Maxim Koltsov6 years ago

src/Data/Swagger.hs+1

compare with master

unifiedsplit

@@ -74,6 +74,7 @@ module Data.Swagger (

74 Example(..),

75 RequestBody(..),

76 MediaTypeObject(..),

77+ Encoding(..),

78 -- ** Schemas

79 -- ** Schemas

79 ParamSchema(..),

80 ParamSchema(..),

src/Data/Swagger/Internal.hs+105−33

@@ -21,7 +21,7 @@ import Prelude.Compat

22import Control.Lens ((&), (.~), (?~))

23import Control.Applicative

24−import Data.Aeson

24+import Data.Aeson hiding (Encoding)

25import qualified Data.Aeson.Types as JSON

26import Data.Data (Data(..), Typeable, mkConstr, mkDataType, Fixity(..), Constr, DataType, constrIndex)

27import Data.Hashable (Hashable)

@@ -186,7 +186,7 @@ data Components = Components

186 { _componentsSchemas :: Definitions Schema

187 , _componentsResponses :: Definitions Response

188 , _componentsParameters :: Definitions Param

189−-- , _componentsExamples

189+ , _componentsExamples :: Definitions Example

190 , _componentsRequestBodies :: Definitions RequestBody

191 , _componentsHeader :: Definitions Header

192 , _componentsSecuritySchemes :: Definitions SecurityScheme

@@ -350,11 +350,59 @@ data RequestBody = RequestBody

350data MediaTypeObject = MediaTypeObject

351 { _mediaTypeObjectSchema :: Maybe (Referenced Schema)

352

353−-- TODO

353+ -- | Example of the media type.

354−-- , _mediaTypeExample

354+ -- The example object SHOULD be in the correct format as specified by the media type.

355−-- , _mediaTypeExamples

355+ , _mediaTypeObjectExample :: Maybe Value

356

357+ -- | Examples of the media type.

358+ -- Each example object SHOULD match the media type and specified schema if present.

359+ , _mediaTypeObjectExamples :: InsOrdHashMap Text (Referenced Example)

360+

361+ -- | A map between a property name and its encoding information.

362+ -- The key, being the property name, MUST exist in the schema as a property.

363+ -- The encoding object SHALL only apply to 'RequestBody' objects when the media type

364+ -- is @multipart@ or @application/x-www-form-urlencoded@.

357−-- , _mediaTypeEncoding :: InsOrdHashMap Text Encoding

365+ , _mediaTypeObjectEncoding :: InsOrdHashMap Text Encoding

366+ } deriving (Eq, Show, Generic, Data, Typeable)

367+

368+data Encoding = Encoding

369+ { -- | The Content-Type for encoding a specific property.

370+ -- Default value depends on the property type: for @string@

371+ -- with format being @binary@ – @application/octet-stream@;

372+ -- for other primitive types – @text/plain@; for object - @application/json@;

373+ -- for array – the default is defined based on the inner type.

374+ -- The value can be a specific media type (e.g. @application/json@),

375+ -- a wildcard media type (e.g. @image/*@), or a comma-separated list of the two types.

376+ _encodingContentType :: Maybe Text

377+

378+ -- | A map allowing additional information to be provided as headers,

379+ -- for example @Content-Disposition@. @Content-Type@ is described separately

380+ -- and SHALL be ignored in this section.

381+ -- This property SHALL be ignored if the request body media type is not a @multipart@.

382+ , _encodingHeaders :: InsOrdHashMap Text (Referenced Header)

383+

384+ -- | Describes how a specific property value will be serialized depending on its type.

385+ -- See Parameter Object for details on the style property.

386+ -- The behavior follows the same values as query parameters, including default values.

387+ -- This property SHALL be ignored if the request body media type

388+ -- is not @application/x-www-form-urlencoded@.

389+ , _encodingStyle :: Maybe Text -- TODO enum

390+

391+ -- | When this is true, property values of type @array@ or @object@ generate

392+ -- separate parameters for each value of the array,

393+ -- or key-value-pair of the map.

394+ -- For other types of properties this property has no effect.

395+ -- When style is form, the default value is @true@. For all other styles,

396+ -- the default value is @false@. This property SHALL be ignored

397+ -- if the request body media type is not @application/x-www-form-urlencoded@.

398+ , _encodingExplode :: Maybe Bool

399+

400+ -- | Determines whether the parameter value SHOULD allow reserved characters,

401+ -- as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2)

402+ -- @:/?#[]@!$&'()*+,;=@ to be included without percent-encoding.

403+ -- The default value is @false@. This property SHALL be ignored if the request body media type

404+ -- is not @application/x-www-form-urlencoded@.

405+ , _encodingAllowReserved :: Maybe Bool

358 } deriving (Eq, Show, Generic, Data, Typeable)

406 } deriving (Eq, Show, Generic, Data, Typeable)

359

407

360newtype MimeList = MimeList { getMimeList :: [MediaType] }

408newtype MimeList = MimeList { getMimeList :: [MediaType] }

@@ -412,6 +460,28 @@ data ParamOtherSchema = ParamOtherSchema

412 , _paramOtherSchemaParamSchema :: ParamSchema 'SwaggerKindParamOtherSchema

460 , _paramOtherSchemaParamSchema :: ParamSchema 'SwaggerKindParamOtherSchema

413 } deriving (Eq, Show, Generic, Typeable, Data)

461 } deriving (Eq, Show, Generic, Typeable, Data)

414

462

463+data Example = Example

464+ { -- | Short description for the example.

465+ _exampleSummary :: Maybe Text

466+

467+ -- | Long description for the example.

468+ -- CommonMark syntax MAY be used for rich text representation.

469+ , _exampleDescription :: Maybe Text

470+

471+ -- | Embedded literal example.

472+ -- The '_exampleValue' field and '_exampleExternalValue' field are mutually exclusive.

473+ --

474+ -- To represent examples of media types that cannot naturally represented in JSON or YAML,

475+ -- use a string value to contain the example, escaping where necessary.

476+ , _exampleValue :: Maybe Value

477+

478+ -- | A URL that points to the literal example.

479+ -- This provides the capability to reference examples that cannot easily be included

480+ -- in JSON or YAML documents. The '_exampleValue' field

481+ -- and '_exampleExternalValue' field are mutually exclusive.

482+ , _exampleExternalValue :: Maybe URL

483+ } deriving (Eq, Show, Generic, Typeable, Data)

484+

415-- | Items for @'SwaggerArray'@ schemas.

485-- | Items for @'SwaggerArray'@ schemas.

416--

486--

417-- @'SwaggerItemsPrimitive'@ should be used only for query params, headers and path pieces.

487-- @'SwaggerItemsPrimitive'@ should be used only for query params, headers and path pieces.

@@ -633,6 +703,8 @@ data NamedSchema = NamedSchema

633-- | Regex pattern for @string@ type.

703-- | Regex pattern for @string@ type.

634type Pattern = Text

704type Pattern = Text

635

705

706+-- TODO examples for params

707+

636data ParamSchema (t :: SwaggerKind *) = ParamSchema

708data ParamSchema (t :: SwaggerKind *) = ParamSchema

637 { -- | Declares the value of the parameter that the server will use if none is provided,

709 { -- | Declares the value of the parameter that the server will use if none is provided,

638 -- for example a @"count"@ to control the number of results per page might default to @100@

710 -- for example a @"count"@ to control the number of results per page might default to @100@

@@ -735,22 +807,6 @@ data Header = Header

735 , _headerParamSchema :: ParamSchema ('SwaggerKindNormal Header)

807 , _headerParamSchema :: ParamSchema ('SwaggerKindNormal Header)

736 } deriving (Eq, Show, Generic, Data, Typeable)

808 } deriving (Eq, Show, Generic, Data, Typeable)

737

809

738−data Example = Example { getExample :: Map MediaType Value }

739− deriving (Eq, Show, Generic, Typeable)

740−

741−exampleConstr :: Constr

742−exampleConstr = mkConstr exampleDataType "Example" ["getExample"] Prefix

743−

744−exampleDataType :: DataType

745−exampleDataType = mkDataType "Data.Swagger.Example" [exampleConstr]

746−

747−instance Data Example where

748− gunfold k z c = case constrIndex c of

749− 1 -> k (z (\m -> Example (Map.mapKeys fromString m)))

750− _ -> error $ "Data.Data.gunfold: Constructor " ++ show c ++ " is not of type Example."

751− toConstr (Example _) = exampleConstr

752− dataTypeOf _ = exampleDataType

753−

754-- | The location of the API key.

810-- | The location of the API key.

755data ApiKeyLocation

811data ApiKeyLocation

756 = ApiKeyQuery

812 = ApiKeyQuery

@@ -898,6 +954,8 @@ deriveGeneric ''SecurityScheme

898deriveGeneric ''Schema

954deriveGeneric ''Schema

899deriveGeneric ''ParamSchema

955deriveGeneric ''ParamSchema

900deriveGeneric ''Swagger

956deriveGeneric ''Swagger

957+deriveGeneric ''Example

958+deriveGeneric ''Encoding

901

959

902-- =======================================================================

960-- =======================================================================

903-- Monoid instances

961-- Monoid instances

@@ -981,21 +1039,21 @@ instance Monoid MediaTypeObject where

981 mempty = genericMempty

1039 mempty = genericMempty

982 mappend = (<>)

1040 mappend = (<>)

983

1041

984−instance Semigroup ExternalDocs where

1042+instance Semigroup Encoding where

985 (<>) = genericMappend

1043 (<>) = genericMappend

986−instance Monoid ExternalDocs where

1044+instance Monoid Encoding where

987 mempty = genericMempty

1045 mempty = genericMempty

988 mappend = (<>)

1046 mappend = (<>)

989

1047

990−instance Semigroup Operation where

1048+instance Semigroup ExternalDocs where

991 (<>) = genericMappend

1049 (<>) = genericMappend

992−instance Monoid Operation where

1050+instance Monoid ExternalDocs where

993 mempty = genericMempty

1051 mempty = genericMempty

994 mappend = (<>)

1052 mappend = (<>)

995

1053

996−instance Semigroup Example where

1054+instance Semigroup Operation where

997 (<>) = genericMappend

1055 (<>) = genericMappend

998−instance Monoid Example where

1056+instance Monoid Operation where

999 mempty = genericMempty

1057 mempty = genericMempty

1000 mappend = (<>)

1058 mappend = (<>)

1001

1059

@@ -1251,7 +1309,12 @@ instance ToJSON MediaTypeObject where

1251 toEncoding = sopSwaggerGenericToEncoding

1309 toEncoding = sopSwaggerGenericToEncoding

1252

1310

1253instance ToJSON Example where

1311instance ToJSON Example where

1254− toJSON = toJSON . Map.mapKeys show . getExample

1312+ toJSON = sopSwaggerGenericToJSON

1313+ toEncoding = sopSwaggerGenericToEncoding

1314+

1315+instance ToJSON Encoding where

1316+ toJSON = sopSwaggerGenericToJSON

1317+ toEncoding = sopSwaggerGenericToEncoding

1255

1318

1256instance ToJSON SecurityDefinitions where

1319instance ToJSON SecurityDefinitions where

1257 toJSON (SecurityDefinitions sd) = toJSON sd

1320 toJSON (SecurityDefinitions sd) = toJSON sd

@@ -1267,6 +1330,8 @@ instance ToJSON (Referenced Schema) where toJSON = referencedToJSON "#/compone

1267instance ToJSON (Referenced Param) where toJSON = referencedToJSON "#/components/parameters/"

1330instance ToJSON (Referenced Param) where toJSON = referencedToJSON "#/components/parameters/"

1268instance ToJSON (Referenced Response) where toJSON = referencedToJSON "#/components/responses/"

1331instance ToJSON (Referenced Response) where toJSON = referencedToJSON "#/components/responses/"

1269instance ToJSON (Referenced RequestBody) where toJSON = referencedToJSON "#/components/requestBodies/"

1332instance ToJSON (Referenced RequestBody) where toJSON = referencedToJSON "#/components/requestBodies/"

1333+instance ToJSON (Referenced Example) where toJSON = referencedToJSON "#/components/examples/"

1334+instance ToJSON (Referenced Header) where toJSON = referencedToJSON "#/components/headers/"

1270

1335

1271instance ToJSON (SwaggerType t) where

1336instance ToJSON (SwaggerType t) where

1272 toJSON SwaggerArray = "array"

1337 toJSON SwaggerArray = "array"

@@ -1408,9 +1473,7 @@ instance FromJSON Responses where

1408 parseJSON _ = empty

1473 parseJSON _ = empty

1409

1474

1410instance FromJSON Example where

1475instance FromJSON Example where

1411− parseJSON js = do

1476+ parseJSON = sopSwaggerGenericParseJSON

1412− m <- parseJSON js

1413− pure $ Example (Map.mapKeys fromString m)

1414

1477

1415instance FromJSON Response where

1478instance FromJSON Response where

1416 parseJSON = sopSwaggerGenericParseJSON

1479 parseJSON = sopSwaggerGenericParseJSON

@@ -1427,6 +1490,9 @@ instance FromJSON RequestBody where

1427instance FromJSON MediaTypeObject where

1490instance FromJSON MediaTypeObject where

1428 parseJSON = sopSwaggerGenericParseJSON

1491 parseJSON = sopSwaggerGenericParseJSON

1429

1492

1493+instance FromJSON Encoding where

1494+ parseJSON = sopSwaggerGenericParseJSON

1495+

1430instance FromJSON SecurityDefinitions where

1496instance FromJSON SecurityDefinitions where

1431 parseJSON js = SecurityDefinitions <$> parseJSON js

1497 parseJSON js = SecurityDefinitions <$> parseJSON js

1432

1498

@@ -1450,7 +1516,9 @@ referencedParseJSON _ _ = fail "referenceParseJSON: not an object"

1450instance FromJSON (Referenced Schema) where parseJSON = referencedParseJSON "#/components/schemas/"

1516instance FromJSON (Referenced Schema) where parseJSON = referencedParseJSON "#/components/schemas/"

1451instance FromJSON (Referenced Param) where parseJSON = referencedParseJSON "#/components/parameters/"

1517instance FromJSON (Referenced Param) where parseJSON = referencedParseJSON "#/components/parameters/"

1452instance FromJSON (Referenced Response) where parseJSON = referencedParseJSON "#/components/responses/"

1518instance FromJSON (Referenced Response) where parseJSON = referencedParseJSON "#/components/responses/"

1453−instance FromJSON (Referenced RequestBody) where parseJSON = referencedParseJSON "#/components/requestBodies"

1519+instance FromJSON (Referenced RequestBody) where parseJSON = referencedParseJSON "#/components/requestBodies/"

1520+instance FromJSON (Referenced Example) where parseJSON = referencedParseJSON "#/components/examples/"

1521+instance FromJSON (Referenced Header) where parseJSON = referencedParseJSON "#/components/headers/"

1454

1522

1455instance FromJSON Xml where

1523instance FromJSON Xml where

1456 parseJSON = genericParseJSON (jsonPrefix "xml")

1524 parseJSON = genericParseJSON (jsonPrefix "xml")

@@ -1513,6 +1581,10 @@ instance HasSwaggerAesonOptions Schema where

1513 swaggerAesonOptions _ = mkSwaggerAesonOptions "schema" & saoSubObject ?~ "paramSchema"

1581 swaggerAesonOptions _ = mkSwaggerAesonOptions "schema" & saoSubObject ?~ "paramSchema"

1514instance HasSwaggerAesonOptions Swagger where

1582instance HasSwaggerAesonOptions Swagger where

1515 swaggerAesonOptions _ = mkSwaggerAesonOptions "swagger" & saoAdditionalPairs .~ [("openapi", "3.0.3")]

1583 swaggerAesonOptions _ = mkSwaggerAesonOptions "swagger" & saoAdditionalPairs .~ [("openapi", "3.0.3")]

1584+instance HasSwaggerAesonOptions Example where

1585+ swaggerAesonOptions _ = mkSwaggerAesonOptions "example"

1586+instance HasSwaggerAesonOptions Encoding where

1587+ swaggerAesonOptions _ = mkSwaggerAesonOptions "encoding"

1516

1588

1517instance HasSwaggerAesonOptions (ParamSchema ('SwaggerKindNormal t)) where

1589instance HasSwaggerAesonOptions (ParamSchema ('SwaggerKindNormal t)) where

1518 swaggerAesonOptions _ = mkSwaggerAesonOptions "paramSchema" & saoSubObject ?~ "items"

1590 swaggerAesonOptions _ = mkSwaggerAesonOptions "paramSchema" & saoSubObject ?~ "items"