当涉及到 API 设计和 Swagger (OpenAPI) 规范时，很少有人能像 Arnaud Lauret 那样充满激情，他最著名的身份是 API 手艺人 (@apihandyman)。Arnaud 在 IT 银行业工作了近 13 年，担任程序员和项目经理，如今，他作为 AXA Banque 的 IT 架构师，负责 API 项目和治理。
今年 9 月，Arnaud 发布了 API 样式手册，该手册旨在通过提供对精选和分类资源的快速便捷访问，帮助 API 设计人员解决 API 设计挑战并构建 API 设计指南。Arnaud 还是 关于编写 OpenAPI 规范的 10 部分 Swagger 教程的创建者。他的教程对于任何刚开始使用 Swagger 开源工具或 SwaggerHub 的人来说都是宝贵的资源。
本月早些时候，我们有幸欢迎 Arnaud 参加我们的 API 专家小组：2017 年的 API 策略开发在 SmartBear 总部。在小组讨论之前，我们与 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 的功能指南。有些书谈论过这一点，但所有这些指南都非常技术性。
有兴趣了解更多吗？
通过 APIHandyman 博客了解 Arnaud 的最新资源。开始使用 OpenAPI 规范了吗？请在此处查看我们的 OpenAPI 资源部分。