Auto-generate Servant-API 面向 Haskell 开发人员的文档

Question

我使用 servant 构建了一个 web-API，它变得越来越大。

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

首先是黑线鳕。 Haddock 将我的代码变成超链接 HTML-pages。整洁的！这特别有用，因为我的 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

黑线鳕变成这样：

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 以漂亮的方式显示长类型，或者我找到了一种方法来显示 haskell 类型 servant-docs.

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

我已经尝试过 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 忽略。使用黑线鳕标题语法 --| 或 -- * 会导致黑线鳕编译错误。

Answer 1

在评论中提到使用每个端点 type 别名。然而，较新的 servant 有 Servant.API.Generic（在 https://haskell-servant.readthedocs.io/en/stable/cookbook/generic/Generic.html 阅读更多内容），这让您可以以更结构化的方式编写 API：

data Public route = Public

  -- | create new user
   { routeNewUser :: route :- "new"    :> ReqBody '[JSON] UserNewRequest    :> Post '[JSON] UserNewResponse

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

  -- | user login
  , routeLogin    :: route :- "login"  :> ReqBody '[JSON] LoginRequest      :> Post '[JSON] LoginResponse
  }

这种方法对于嵌套 APIs 有点棘手，但它在 "linear" api 中有很多好处。

Auto-generate Servant-API 面向 Haskell 开发人员的文档

Auto-generate Servant-API documentation for Haskell developers

haskell

documentation-generation

haddock

servant