谈到 API 设计和 Swagger (OpenAPI) 规范，很少有人能像 Arnaud Lauret 那样充满热情，他以 API Handyman (@apihandyman) 的名号而闻名。Arnaud 在 IT 银行业工作了近 13 年，既是程序员也是项目经理，如今在 AXA Banque 担任 IT 架构师，负责 API 项目和治理。
9 月，Arnaud 发布了 API Stylebook，旨在通过提供对精选和分类资源的快速便捷访问，帮助 API 设计师解决 API 设计挑战并制定 API 设计指南。Arnaud 还是 一个 10 部分的 Swagger 教程 的作者，该教程关于编写 OpenAPI 规范。他的教程对于任何刚开始使用 Swagger 开源工具或 SwaggerHub 的人来说都是宝贵的资源。
本月早些时候，我们很荣幸在 SmartBear 总部邀请 Arnaud 参加我们的 API 专家小组：《制定 2017 年 API 策略》。在小组讨论之前，我们与 Arnaud 进行了座谈，了解他开始使用 Swagger 的经验以及优秀 API 设计的共同特征。
您能谈谈您开始使用 Swagger 的经验吗？
几年前我们启动了一个 API 项目，我们希望为我们的 API 提供文档，所以我们开始使用 Swagger 注解从代码生成文档。那时我还没有意识到这个注解背后是一种格式——OpenAPI 规范。最初的结果并不理想，因为我们没有给编写注解的开发者足够的指导，所以结果作为文档来说并不是真正可用的。
就在那时，Swagger 2.0 发布了——它带来了新的规范、编辑器和 YAML 的使用。我们需要更新我们的文档，这非常复杂，因为文档是在代码中的。所以我开始尝试这种格式，通过检索现有的生成文档并将其转换为 Swagger 2.0，我意识到它真的很容易解析和操作。
我创建了另一个模块，它纠正了文档中的许多问题。这激发了我深入研究这种格式的渴望。那时我感觉到我们可以用它做很多很多事情。我们首先使用 OpenAPI 规范格式编写规范。我们计划在设计时编写一些控制，只需解析规范，查看新设计的 API 是否符合我们的指南——新文档是否完整，是否到处都有描述……
一步一步地，我每天都发现新事物。最终，我在我的博客上写了一个 10 部分的教程。关于该规范最重要的一点是它非常简单，你不需要任何复杂的东西来解析它并用它做事情。
您在 REST API 中看到了哪些常见的设计特征/准则？
所有的准则都真正关注于——好吧，我们想做一个 REST API——什么是 REST API？我们有资源，我们必须使用 HTTP 协议，正确的 HTTP 状态等等。它们以不同的方式讲述这个故事，但它们都从非常技术的角度以相同的方式解释相同的事情。当你问这个问题时，我突然想到，它们并没有谈论真正的问题——如何看待 API 作为提供功能的服务。而不仅仅是提供带有 HTTP 协议的资源。我们必须有这些类型的文档，因为我们需要从技术的角度为 API 设计设定框架。
但我也认为所有需要设计 API 的公司，都需要从功能角度出发的功能性指南来设计 API。有一些书籍谈论过这一点，但所有这些指南都非常技术化。
有兴趣了解更多？
随时了解 Arnaud 在 APIHandyman 博客上的最新资源。刚开始使用 OpenAPI 规范？请在此查看我们的 OpenAPI 资源部分。