为Haskell开发人员自动生成Servant-API文档

Question

我使用越来越大的servant构建了一个web-API。

我知道有两种方法可以自动为api创建文档。

首先，有蠢货。 Haddock将我的代码转换为超链接的HTML页面。整齐！这特别有用，因为我的api端点往往会延伸到几个模块，现在我可以浏览它们并找到相关的类型信息。

然而，haddock并没有一种正确显示这些线条的方法：

type Public =
       "new"    :> ReqBody '[JSON] UserNewRequest    :> Post '[JSON] UserNewResponse
  :<|> "exists" :> ReqBody '[JSON] UserExistsRequest :> Post '[JSON] Bool
  :<|> "login"  :> ReqBody '[JSON] LoginRequest      :> Post '[JSON] LoginResponse

Haddock把它变成这样的东西：

type Public = ("new" :> (ReqBody '[JSON] UserNewRequest :> Post '[JSON] UserNewResponse)) :<|> (("exists" :> (ReqBody '[JSON] UserExistsRequest :> Post '[JSON] Bool)) :<|> ("login" :> (ReqBody '[JSON] LoginRequest :> Post '[JSON] LoginResponse)))

......甚至添加括号。具有讽刺意味的是，代码中的格式更漂亮，仅仅因为换行符。

第二，有servant-docs。但是，servant-docs非常一致地构建了端点的文档，并提供了很好的钩子来添加示例，例如在JSON中。 Servant-docs的目的不是提供haskell类型的信息 - 这就是我所追求的。

---

所以要么，我找到一种方法让haddock以漂亮的方式显示长类型，或者我找到一种方法来显示带有servant-docs的haskell类型。

在这两种情况下，它似乎都不适合他们的设计。我可能完全需要别的东西。

---

我和haddock已经尝试过的了：

type Public =

  -- create new user
       "new"    :> ReqBody '[JSON] UserNewRequest    :> Post '[JSON] UserNewResponse

  -- check if user exists
  :<|> "exists" :> ReqBody '[JSON] UserExistsRequest :> Post '[JSON] Bool

  -- user login
  :<|> "login"  :> ReqBody '[JSON] LoginRequest      :> Post '[JSON] LoginResponse

它是有效的haskell，但haddock忽略了这些评论。使用haddock标题语法--|或-- *会导致haddock编译错误。