| Copyright | (C) 2016-2018 Oleg Grenrus |
|---|---|
| License | BSD-3-Clause |
| Maintainer | Oleg Grenrus <[email protected]> |
| Safe Haskell | None |
| Language | Haskell2010 |
Servant.Swagger.UI
Description
Provides SwaggerUI and corresponding swaggerSchemaUIServer to embed
swagger ui into the application.
All of the UI files are embedded into the binary.
Note that you need to depend on particular swagger-ui compatible provider:
- https://hackage.haskell.org/package/swagger2
- https://hackage.haskell.org/package/openapi3
An example:
-- | Actual API.
type BasicAPI = Get '[PlainText, JSON] Text
:<|> "cat" :> Capture ":name" CatName :> Get '[JSON] Cat
-- | API type with bells and whistles, i.e. schema file and swagger-ui.
type API = SwaggerSchemaUI "swagger-ui" "swagger.json"
:<|> BasicAPI
-- | Servant server for an API
server :: Server API
server = swaggerSchemaUIServer swaggerDoc
:<|> (pure "Hello World" :<|> catEndpoint)
where
catEndpoint name = pure $ Cat name False
Synopsis
- type SwaggerSchemaUI (dir :: Symbol) (schema :: Symbol) = SwaggerSchemaUI' dir (schema :> Get '[JSON] Value)
- type SwaggerSchemaUI' (dir :: Symbol) api = api :<|> (dir :> (Get '[HTML] (SwaggerUiHtml dir api) :<|> (("index.html" :> Get '[HTML] (SwaggerUiHtml dir api)) :<|> Raw)))
- swaggerSchemaUIServer :: forall api a (dir :: Symbol). (Server api ~ Handler Value, ToJSON a) => a -> Server (SwaggerSchemaUI' dir api)
- swaggerSchemaUIServerT :: forall (m :: Type -> Type) api a (dir :: Symbol). (Monad m, ServerT api m ~ m Value, ToJSON a) => a -> ServerT (SwaggerSchemaUI' dir api) m
- swaggerSchemaUIServer' :: forall api (dir :: Symbol). Server api -> Server (SwaggerSchemaUI' dir api)
- swaggerSchemaUIServerT' :: forall (m :: Type -> Type) api (dir :: Symbol). Monad m => ServerT api m -> ServerT (SwaggerSchemaUI' dir api) m
- swaggerUiIndexTemplate :: Text
- swaggerUiFiles :: [(FilePath, ByteString)]
Swagger UI API
type SwaggerSchemaUI (dir :: Symbol) (schema :: Symbol) = SwaggerSchemaUI' dir (schema :> Get '[JSON] Value) #
Swagger schema + ui api.
SwaggerSchemaUI "swagger-ui" "swagger.json" will result into following hierarchy:
/swagger.json /swagger-ui /swagger-ui/index.html /swagger-ui/...
This type does not actually force served type to be Swagger from swagger2 package,
it could be arbitrary aeson Value.
type SwaggerSchemaUI' (dir :: Symbol) api = api :<|> (dir :> (Get '[HTML] (SwaggerUiHtml dir api) :<|> (("index.html" :> Get '[HTML] (SwaggerUiHtml dir api)) :<|> Raw))) #
Use SwaggerSchemaUI' when you need even more control over
where swagger.json is served (e.g. subdirectory).
swaggerSchemaUIServer :: forall api a (dir :: Symbol). (Server api ~ Handler Value, ToJSON a) => a -> Server (SwaggerSchemaUI' dir api) Source #
Serve Swagger UI on /dir using api as a Swagger spec source.
swaggerSchemaUIServer :: Swagger -> Server (SwaggerSchemaUI schema dir) swaggerSchemaUIServer :: OpenApi -> Server (SwaggerSchemaUI schema dir)
swaggerSchemaUIServerT :: forall (m :: Type -> Type) api a (dir :: Symbol). (Monad m, ServerT api m ~ m Value, ToJSON a) => a -> ServerT (SwaggerSchemaUI' dir api) m Source #
Serve Swagger UI on /dir using api as a Swagger spec source.
Generalized to ServerT
swaggerSchemaUIServerT :: Swagger -> ServerT (SwaggerSchemaUI schema dir) m swaggerSchemaUIServerT :: OpenApi -> ServerT (SwaggerSchemaUI schema dir) m
swaggerSchemaUIServer' :: forall api (dir :: Symbol). Server api -> Server (SwaggerSchemaUI' dir api) Source #
Use a custom server to serve the Swagger spec source.
This allows even more control over how the spec source is served. It allows, for instance, serving the spec source with authentication, customizing the response based on the client or serving a swagger.yaml instead.
swaggerSchemaUIServerT' :: forall (m :: Type -> Type) api (dir :: Symbol). Monad m => ServerT api m -> ServerT (SwaggerSchemaUI' dir api) m Source #
Use a custom server to serve the Swagger spec source.
This allows even more control over how the spec source is served. It allows, for instance, serving the spec source with authentication, customizing the response based on the client or serving a swagger.yaml instead.
Generalized to ServerT
Official swagger ui
swaggerUiFiles :: [(FilePath, ByteString)] Source #