diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +1.1.5 +----- + +* Notes: + * `servant-0.13` compatible release + * Drops compatibility with previous `servant` versions. + 1.1.4 ----- diff --git a/servant-swagger.cabal b/servant-swagger.cabal --- a/servant-swagger.cabal +++ b/servant-swagger.cabal @@ -1,22 +1,37 @@ name: servant-swagger -version: 1.1.4 +version: 1.1.5 synopsis: Generate Swagger specification for your servant API. -description: Please see README.md +description: + Swagger™ is a project used to describe and document RESTful APIs. + Unlike Servant it is language-agnostic and thus is quite popular among developers + in different languages. It also exists for a longer time and has more tools to work with. + . + This package provides means to generate Swagger specification for a Servant API + and also to partially test whether API conforms with its specification. + . + Generated Swagger specification then can be used for many things such as + . + * displaying interactive documentation using [Swagger UI](http://swagger.io/swagger-ui/); + . + * generating clients and servers in many languages using [Swagger Codegen](http://swagger.io/swagger-codegen/); + . + * and [many others](http://swagger.io/open-source-integrations/). homepage: https://github.com/haskell-servant/servant-swagger bug-reports: https://github.com/haskell-servant/servant-swagger/issues license: BSD3 license-file: LICENSE author: David Johnson, Nickolay Kudasov maintainer: nickolay.kudasov@gmail.com -copyright: (c) 2015-2016, Servant contributors +copyright: (c) 2015-2018, Servant contributors category: Web, Servant, Swagger build-type: Custom -cabal-version: >=1.18 +cabal-version: 1.18 tested-with: GHC==7.8.4, GHC==7.10.3, GHC==8.0.2, - GHC==8.2.1 + GHC==8.2.2 + extra-source-files: README.md , CHANGELOG.md @@ -60,8 +75,9 @@ , bytestring >=0.10.4.0 && <0.11 , http-media >=0.6.3 && <0.8 , insert-ordered-containers >=0.1.0.0 && <0.3 - , lens >=4.7.0.1 && <4.16 - , servant >=0.5 && <0.13 + , lens >=4.7.0.1 && <4.17 + , servant >=0.13 && <0.14 + , singleton-bool >=0.1.3 && <0.2 , swagger2 >=2.1 && <2.3 , text >=1.2.0.6 && <1.3 , unordered-containers >=0.2.5.1 && <0.3 @@ -89,6 +105,7 @@ type: exitcode-stdio-1.0 hs-source-dirs: test main-is: Spec.hs + build-tool-depends: hspec-discover:hspec-discover build-depends: base , aeson , aeson-qq >=0.8.1 diff --git a/src/Servant/Swagger/Internal.hs b/src/Servant/Swagger/Internal.hs --- a/src/Servant/Swagger/Internal.hs +++ b/src/Servant/Swagger/Internal.hs @@ -30,6 +30,9 @@ import GHC.TypeLits import Network.HTTP.Media (MediaType) import Servant.API +import Servant.API.Description (FoldDescription, reflectDescription) +import Servant.API.Modifiers (FoldRequired) +import Data.Singletons.Bool import Servant.Swagger.Internal.TypeLevel.API @@ -71,10 +74,8 @@ instance HasSwagger Raw where toSwagger _ = mempty & paths . at "/" ?~ mempty -#if MIN_VERSION_servant(0,11,0) instance HasSwagger EmptyAPI where toSwagger _ = mempty -#endif -- | All operations of sub API. -- This is similar to @'operationsOf'@ but ensures that operations @@ -214,7 +215,7 @@ where piece = symbolVal (Proxy :: Proxy sym) -instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub) => HasSwagger (Capture sym a :> sub) where +instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub, KnownSymbol (FoldDescription mods)) => HasSwagger (Capture' mods sym a :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy sub) & addParam param & prependPath capture @@ -222,21 +223,21 @@ where pname = symbolVal (Proxy :: Proxy sym) tname = Text.pack pname + transDesc "" = Nothing + transDesc desc = Just (Text.pack desc) capture = "{" <> pname <> "}" param = mempty & name .~ tname + & description .~ transDesc (reflectDescription (Proxy :: Proxy mods)) & required ?~ True & schema .~ ParamOther (mempty & in_ .~ ParamPath & paramSchema .~ toParamSchema (Proxy :: Proxy a)) -#if MIN_VERSION_servant(0,8,1) -- | Swagger Spec doesn't have a notion of CaptureAll, this instance is the best effort. instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub) => HasSwagger (CaptureAll sym a :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy (Capture sym a :> sub)) -#endif -#if MIN_VERSION_servant(0,12,0) instance (KnownSymbol desc, HasSwagger api) => HasSwagger (Description desc :> api) where toSwagger _ = toSwagger (Proxy :: Proxy api) & allOperations.description %~ (Just (Text.pack (symbolVal (Proxy :: Proxy desc))) <>) @@ -244,19 +245,23 @@ instance (KnownSymbol desc, HasSwagger api) => HasSwagger (Summary desc :> api) where toSwagger _ = toSwagger (Proxy :: Proxy api) & allOperations.summary %~ (Just (Text.pack (symbolVal (Proxy :: Proxy desc))) <>) -#endif -instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub) => HasSwagger (QueryParam sym a :> sub) where +instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub, SBoolI (FoldRequired mods), KnownSymbol (FoldDescription mods)) => HasSwagger (QueryParam' mods sym a :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy sub) & addParam param & addDefaultResponse400 tname where tname = Text.pack (symbolVal (Proxy :: Proxy sym)) + transDesc "" = Nothing + transDesc desc = Just (Text.pack desc) param = mempty & name .~ tname - & schema .~ ParamOther (mempty - & in_ .~ ParamQuery - & paramSchema .~ toParamSchema (Proxy :: Proxy a)) + & description .~ transDesc (reflectDescription (Proxy :: Proxy mods)) + & required ?~ reflectBool (Proxy :: Proxy (FoldRequired mods)) + & schema .~ ParamOther sch + sch = mempty + & in_ .~ ParamQuery + & paramSchema .~ toParamSchema (Proxy :: Proxy a) instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub) => HasSwagger (QueryParams sym a :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy sub) @@ -266,11 +271,13 @@ tname = Text.pack (symbolVal (Proxy :: Proxy sym)) param = mempty & name .~ tname - & schema .~ ParamOther (mempty - & in_ .~ ParamQuery - & paramSchema .~ (mempty - & type_ .~ SwaggerArray - & items ?~ SwaggerItemsPrimitive (Just CollectionMulti) (toParamSchema (Proxy :: Proxy a)))) + & schema .~ ParamOther sch + sch = mempty + & in_ .~ ParamQuery + & paramSchema .~ pschema + pschema = mempty + & type_ .~ SwaggerArray + & items ?~ SwaggerItemsPrimitive (Just CollectionMulti) (toParamSchema (Proxy :: Proxy a)) instance (KnownSymbol sym, HasSwagger sub) => HasSwagger (QueryFlag sym :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy sub) @@ -286,19 +293,23 @@ & paramSchema .~ (toParamSchema (Proxy :: Proxy Bool) & default_ ?~ toJSON False)) -instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub) => HasSwagger (Header sym a :> sub) where +instance (KnownSymbol sym, ToParamSchema a, HasSwagger sub, SBoolI (FoldRequired mods), KnownSymbol (FoldDescription mods)) => HasSwagger (Header' mods sym a :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy sub) & addParam param & addDefaultResponse400 tname where tname = Text.pack (symbolVal (Proxy :: Proxy sym)) + transDesc "" = Nothing + transDesc desc = Just (Text.pack desc) param = mempty & name .~ tname + & description .~ transDesc (reflectDescription (Proxy :: Proxy mods)) + & required ?~ reflectBool (Proxy :: Proxy (FoldRequired mods)) & schema .~ ParamOther (mempty & in_ .~ ParamHeader & paramSchema .~ toParamSchema (Proxy :: Proxy a)) -instance (ToSchema a, AllAccept cs, HasSwagger sub) => HasSwagger (ReqBody cs a :> sub) where +instance (ToSchema a, AllAccept cs, HasSwagger sub, KnownSymbol (FoldDescription mods)) => HasSwagger (ReqBody' mods cs a :> sub) where toSwagger _ = toSwagger (Proxy :: Proxy sub) & addParam param & addConsumes (allContentType (Proxy :: Proxy cs)) @@ -306,9 +317,12 @@ & definitions %~ (<> defs) where tname = "body" + transDesc "" = Nothing + transDesc desc = Just (Text.pack desc) (defs, ref) = runDeclare (declareSchemaRef (Proxy :: Proxy a)) mempty param = mempty & name .~ tname + & description .~ transDesc (reflectDescription (Proxy :: Proxy mods)) & required ?~ True & schema .~ ParamBody ref