@@ -24,42 +24,44 @@
2424-- /An example:/
2525--
2626-- @
27−-- -- | Actual API
27+-- -- | Actual API.
2828-- type BasicAPI = Get '[PlainText, JSON] Text
2929-- :\<|> "cat" :> Capture ":name" CatName :> Get '[JSON] Cat
3030--
31−-- -- | Swagger schema endpoint
31+-- -- | Swagger schema endpoint.
3232-- type SwaggerSchemaEndpoint = "swagger.js" :> Get '[JSON] Swagger
3333--
3434-- -- | Unhabitated new data type, to be able to refer to API type from the API type.
3535-- data API
3636--
37−-- -- | Underlying API type
38−-- type API' = BasicAPI
39−-- :\<|> SwaggerSchemaEndpoint
37+-- -- | Underlying API type.
38+-- --
39+-- -- NOTE: place BasicAPI last for it not to override SwaggerSchemaEndpoing and SwaggerUI.
40+-- -- If you place BasicAPI first and it has Raw endpoint at root Swagger schema and UI won't work.
41+-- type API' = SwaggerSchemaEndpoint
4042-- :\<|> 'SwaggerUI' "ui" SwaggerSchemaEndpoint API
41−--
42−-- -- Unfortunately we have to write those trivial instances.
43+-- :\<|> BasicAPI
4344--
4445-- -- Optionally we can do:
45−-- -- data API'= BasicAPI
46−-- -- :\<|> SwaggerSchemaEndpoint
4746-- --
48−-- -- | Underlying API type
49−-- -- type API = API'
50−-- -- :\<|> SwaggerUI "ui" SwaggerSchemaEndpoint API'
47+-- -- type API' = SwaggerSchemaEndpoint
48+-- -- :\<|> BasicAPI
49+-- --
50+-- -- type API = SwaggerUI "ui" SwaggerSchemaEndpoint API'
51+-- -- :\<|> API'
52+--
53+-- -- Unfortunately we have to write these trivial instances.
5154--
52−-- instance HasServer API where
55+-- instance HasServer API context where
5356-- type ServerT API m = ServerT API' m
5457-- route _ = route (Proxy :: Proxy API')
5558--
5659-- type instance IsElem' e API = IsElem e API'
5760--
5861-- server :: Server API
59−-- server =
60−-- (pure "Hello World" :\<|> catEndpoint)
61−-- :\<|> pure swaggerDoc
62+-- server = pure swaggerDoc
6263-- :\<|> 'swaggerUIServer'
64+-- :\<|> (pure "Hello World" :\<|> catEndpoint)
6365-- where
6466-- catEndpoint name = pure $ Cat name False
6567-- @
@@ -103,6 +105,7 @@ instance (IsElem endpoint api, HasLink endpoint, MkLink endpoint ~ URI)
103105 uri = safeLink (Proxy :: Proxy api) (Proxy :: Proxy endpoint) :: URI
104106 url = T.pack $ "/" <> uriPath uri -- TODO: do we need more?
105107
108+-- | Serve Swagger UI on @/<dir>@ using @endpoint@ as Swagger spec source for @api@.
106109swaggerUIServer :: Server (SwaggerUI dir endpoint api)
107110swaggerUIServer = return SwaggerUiHtml :<|> return SwaggerUiHtml :<|> rest
108111 where rest = staticApp $ embeddedSettings swaggerUiFiles