Servant.Swagger.UI

Provides SwaggerUI and corresponding swaggerSchemaUIServer to embed swagger ui into the application.

All of the UI files are embedded into the binary.

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

Swagger UI API

type SwaggerSchemaUI (dir :: Symbol) (schema :: Symbol) = SwaggerSchemaUI' dir (schema :> Get '[JSON] Swagger)

Swagger schema + ui api.

SwaggerSchemaUI "swagger-ui" "swagger.json" will result into following hierarchy:

/swagger.json
/swagger-ui
/swagger-ui/index.html
/swagger-ui/...

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 :: Server api ~ Handler Swagger => Swagger -> Server (SwaggerSchemaUI' dir api)

Serve Swagger UI on /dir using api as a Swagger spec source.

swaggerSchemaUIServer :: Swagger -> Server (SwaggerSchemaUI schema dir)

swaggerSchemaUIServer' :: Server api -> Server (SwaggerSchemaUI' dir api)

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.

Official swagger ui

swaggerUiIndexTemplate :: Text

swaggerUiFiles :: [(FilePath, ByteString)]