导入
记录我们的 API
文档的重要性概述、现有文档编写方法以及我们将采用的方法。
我们是否需要文档？
我们必须解决一个缺失的环节：我们需要为我们的 API 编写文档。
但代码注释难道不够吗？
不是！即使暂且不讨论代码注释是否规范的问题，我们这里重点聚焦于 API 文档的编写。
如今的事实标准似乎是使用 Swagger 来实现这一点。为了保持简单，我们将沿用这一方案。此外，附带一份文本形式的文档（哪怕只是一个小型文件）也是有益的，它应说明我们 API 的一些特殊之处。项目越大，越早可能暴露出逻辑上的缺陷，而这些缺陷由于各种原因可能无法轻易修改。
为什么我们需要文档？
当前状况
...
*Swagger* 提供了一些工具支持，目前也有大量项目致力于将其集成到你偏好的 Web 框架或工具包中。
在许多情况下，将 Swagger UI 与我们的服务捆绑，并通过特定路径提供访问是一个不错的选择。
根据你的需求和运行环境，我们可能希望对这个路径进行身份验证保护，并支持在生产环境中可配置地关闭该功能。
有了 UI 之后，我们需要决定走哪条路：
- 手动编写
swagger.yml文件来描述我们的 API，生成 JSON 并作为静态资源交付。 - 使用某个库在运行时动态生成 JSON。
我们应该选择哪条路径？
现在我们来比较这两种方法的优缺点。
使用 1swagger.yml | 使用库 |
|---|---|
| 描述内容基本固定不变 | 描述内容能真实反映实际代码 |
| 避免运行时可能出现的性能影响和其他问题 | 可能生成奇怪的推断类型，如 Future1 等 |
| 需要额外想办法验证服务是否确实按描述返回内容 | 大量依赖注解来使 API 描述可用 |
| 代码与描述解耦 | 代码与描述紧密耦合 |
对于第一种方式，常用的工具是 Swagger Editor。
而对于倾向于非纯函数式方式的开发者，可以使用 swagger-akka-http 库。
但难道我们不能做得更好吗？
答案是：可以！我们可以利用静态类型来描述 API，让编译器进行检查，并自动生成服务器端和客户端代码。
诚然，Swagger 也支持从定义自动生成代码，但通常（如果不是总是），这些生成的代码只是临时一次性使用的方案——一旦需要重新生成，我们就不得不丢失所有手动修改的内容。