如何使用ExDoc为Elixir项目的API路由生成开发文档

结论 #

可以直接通过ExDoc实现API路由的文档编写，主流有两种实现方案，具体操作如下：

方案1：手动编写（适合路由较少的小型项目） #

直接在Router模块的@moduledoc模块文档中手动整理路由信息，编写的内容会直接渲染到ExDoc生成的Router模块页面中，示例代码如下：

defmodule MyApp.Router do
  use MyApp.Web, :router

  @moduledoc """
  应用路由总览

  ## 对外API接口
  ### v1版本接口
  | 请求方法 | 路径 | 对应控制器 | 动作 | 接口说明 |
  |---------|------|------------|------|----------|
  | POST | `/api/v1/test` | `MyApp.Api.V1.MyController` | `:test` | 业务测试接口 |
  """

  # 原有路由逻辑
  scope "/api", MyApp.Api, as: :api do
    pipe_through :api

    scope "/v1", V1, as: :v1 do
      post "/test", MyController, :test
    end
  end
end

你可以根据需要自行扩展字段，比如加入请求参数示例、返回值结构、权限要求等内容。

方案2：自动生成（适合路由迭代快的中大型项目） #

Phoenix Router会在编译后把所有路由信息存储在__routes__()函数返回的结构体列表中，你可以通过自定义宏在编译阶段自动提取路由信息，注入到模块文档中，不需要手动维护。

操作步骤 #

1. 先定义路由文档生成辅助宏

defmodule RouterDocHelper do
  defmacro generate_router_doc do
    quote bind_quoted: [routes: __MODULE__.__routes__()] do
      # 过滤仅保留对外API路由，可根据自己的需求调整过滤规则
      api_routes = Enum.filter(routes, &String.starts_with?(&1.path, "/api"))

      route_docs = Enum.map(api_routes, fn route ->
        "| #{route.verb} | #{route.path} | #{inspect route.plug} | `:#{route.plug_opts}` |"
      end) |> Enum.join("\n")

      @moduledoc """
      应用自动生成路由列表
      ## 对外API接口
      | 请求方法 | 路径 | 对应控制器 | 动作 |
      |---------|------|------------|------|
      #{route_docs}
      """
    end
  end
end

2. 在Router模块中调用宏
   注意宏必须放在所有路由定义的后面，才能拿到完整的路由信息：

defmodule MyApp.Router do
  use MyApp.Web, :router
  require RouterDocHelper

  # 原有路由逻辑
  scope "/api", MyApp.Api, as: :api do
    pipe_through :api

    scope "/v1", V1, as: :v1 do
      post "/test", MyController, :test
    end
  end

  # 所有路由定义完成后调用宏生成文档
  RouterDocHelper.generate_router_doc()
end

如果需要补充接口说明、参数等自定义内容，你可以给每个路由增加自定义注解，在宏提取路由时同步解析注解内容合并到文档中即可。

内容的提问来源于stack exchange，提问作者Jeremie