API已经非常流行，但是开发人员在缺少文档，以及产品经理需求不完整的时候，要想生成API代码任然是件痛苦的事情。本文探讨Swagger如何在应用创建的流程里，帮助保证代码和文档的一致性。

我们都认同API很好这一点，但是它的构建过程很痛苦。需要跟踪很多细节，在产品经理的想法变成文档规范，再变成开发人员代码的过程中，这些细节很容易就乱成一团。我们无法帮助改善文档环节(除非项目经理会写代码)，但是如果使用Swagger的话，保持文档和代码的同步会很容易。

Swagger是一个工具，能够让任何拥有合适技术能力的人定义API，生成文档，并且甚至生成支持该API的代码。使用在线Swagger编辑器，你可以使用YAML设计API，这是一种人类可读的类似XML的语言。通过键入映射到部分URL的字符串，来定义端点（称为路径）。然后定义输入参数和输出数据的类型，想要实现的安全特性，然后就可以了。

用户可以查看的Swagger编辑器的一个示例是Instagram API（图1）。（如果你进入编辑器，选择File -> Open Example，还可以选择其他一些示例。）

图1. Swagger查看Instagram API代码

图1中的其他数据中，可以看到定义了八个路径（路径以单引号开头，点击行号后面的小的钻石图标，可以展开该节点以便查看细节）。打开这些路径的其中一个（图2），就可以看到其要求的GET HTTP动词。可以阅读描述，看到它要求三个参数。如果调用成功（响应为200），它就会返回一个对象数组，在最下面的Media定义部分定义。

图2.查看定义路径之一

类似得，可以打开Media的定义，查看该对象的属性细节，包括嵌入的对象（图3只显示了Media定义的一部分）。

图3. Media定义的部分视图

使用Swagger编辑器定义API很方便，但是它并不比其他工具更加容易。但是，在编辑器的右边栏，会自动生成所描述的API的HTML文档（图4）。文档很完整，易于阅读，并且提供了所描述API调用的尝试方式。点击底部的“Try this operation（试试该方法）”按钮，允许用户输入参数，发起调用，并且查看结果。

图4.自动生成的文档

这些特性都让这个工具很有用。使用Generate Server和Generate Client菜单选项（图5），能够以你喜欢的任意语言生成代码，从而提供或者消费该API。这个代码生成工具本身就能够帮助用户节约很多枯燥的编程时间，更不用说在API生命周期里做出很多变更时能够带给大家的帮助。另外，在使用导出功能创建本地文本文件时，整个流程完美得契合源代码控制策略。用户还可以发布文件，这样其他开发人员能够和你的数据轻松集成。

图5.使用Generate Server和Generate Client选项

编写API代码很有必要但是也很费时。使用Swagger设计API并且发布YAML能够让这个过程对于内部开发人员，以及想要消费你的数据的开发人员的工作更加简单。