序言
编写目的
本文先容如何利用Swagger编写API文档。通过阅读本文，你可以：
理解swagger是什么
节制利用swagger编写API文档的基本方法
第 1 章 简介
1.1 Swagger
Swagger（丝袜哥）给人第一印象便是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。
Swagger是一个大略但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开拓职员，利用险些所有的当代编程措辞，都在支持和利用Swagger。利用Swagger天生API，我们可以得到交互式文档，自动天生代码的SDK以及API的创造特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等天下有名企业建立起了一套基于RESTful API的完美做事系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在github。
1.2 OpenAPI 规范
OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的措辞，来规范RESTful做事开拓过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：
有关该API的一样平常性描述
可用路径（/资源）
在每个路径上的可用操作（获取/提交...）
每个操作的输入/输出格式
目前V2.0版本的OpenAPI规范（也便是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，构造清晰，方便随时查阅。关于规范的学习和理解，本文末了还有个彩蛋。
1.3 为啥要利用 OpenAPI 规范？
OpenAPI 规范这类 API 定义措辞能够帮助你更大略、快速的表述 API，尤其是在 API 的设计阶段浸染特殊突出
根据 OpenAPI 规范编写的二进制文本文件，能够像代码一样用任何 VCS 工具管理起来
一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、谈论、自测的根本
部分或者全部代码自动天生的根据
其他主要的浸染，比如开放平台开拓者的手册...
1.4 如何编写 API 文档？
1.4.1 措辞 JSON vs YAML
1.4.2 基于 PHP 注释的办法
第 2 章 从零开始
这一章紧张先容 API 的基本组成部分，包括供应给 API 消费者（所有可能访问API的个体，下简称“消费者”）的的不同 HTTP 要求方法、路径，要乞降体中的参数，以及返回给消费者的不同 HTTP 状态及相应体。
<?php/ @SWG\Swagger( swagger=\"大众2.0\"大众, schemes={\公众https\"大众}, host=\公众tcmzapi.emao.com\公众, basePath=\"大众/\公众, @SWG\Info( version=\"大众1.0.0\"大众, title=\"大众淘车猫中转库 Api 文档\"大众, description=\"大众淘车猫中转库 Api 文档\公众 ) )/
这个文档的内容分成四部分，下面分别来解释。
2.1.1 OpenAPI 规范的版本号
首先我们要通过一个 swagger 属性来声明 OpenAPI 规范的版本。
<?php/ @SWG\Swagger( swagger=\"大众2.0\"大众 )/
你没看错，是 swagger，上面已经先容了，OpenAPI 规范是基于 Swagger的，在未来的版本中，这个属性可能会换成别的。 目前这个属性的值，暂时只能填写为 2.0。
2.1.2 API 描述信息
然后我们须要解释一下API文档的干系信息，比如API文档版本（把稳不同于上面的规范版本）、API文档名称已经可选的描述信息。
<?php/ @SWG\Info( version=\公众1.0.0\"大众, title=\"大众淘车猫中转库 Api 文档\公众, description=\"大众淘车猫中转库 Api 文档\公众 )/
version：API 文档版本
title：API 文档标题
description：API文档描述
2.1.3 API 的 URL
作为web API，一个很主要的信息便是用来给消费者利用的根URL，可以用协议（http或者https）、主机名、根路径来描述：
<?php/ @SWG\Swagger( schemes={\"大众https\"大众}, host=\"大众tcmapi.emao.com\"大众, basePath=\"大众/v1\"大众 )/
这这个例子中，消费者把 https://tcmapi.emao.com/v1 作为根节点来访问各种 API。由于和详细环境有关，不涉及 API 描述的根本内容，以是这部分信息是可选的。
schemes：协议，可以是多个
host：主机名
basePath：根路径
2.2 定义一个 API 操作
如果我们要展示一组用户信息，可以这样描述：
<?php/ @SWG\Swagger( swagger=\"大众2.0\"大众 schemes={\"大众https\公众}, host=\"大众tcmapi.emao.com\"大众, basePath=\公众/v1.0\公众, @SWG\Info( version=\"大众1.0.0\"大众, title=\公众淘车猫 Api 文档\公众, description=\"大众淘车猫 Api 文档\"大众 ) ) @SWG\Get( path=\公众/persons\"大众, summary=\公众获取一些人\公众, description=\公众返回包含所有人的列表。\"大众, @SWG\Response( response=200, description=\"大众一个用户列表\公众, @SWG\Schema( type=\"大众array\"大众, @SWG\Items( required={\"大众username\"大众} @SWG\Properties() ) ), ), )/
Get：要求的 HTTP 方法，支持 GET/POST/PUT/DELETE 等 HTTP 标准要求方法
path：要求的路径
summary：接口简介
tags：接口标签，可以是多个
description：接口描述，支持 Markdown 语法
operationId：操作的 ID，须要唯一
2.2.1 添加一个 路径 (path)
我们添加一个 /persons 的 路径，用来访问一组用户信息
2.2.2 在路径中添加一个 HTTP 方法
在每个路径中，我们可以添加任意的HTTP动词，如GET/POST/PUT/DELETE等来操作所须要的资源。
比如须要展示一组用户信息，我们可以在/person 路径中添加 get 方法，同时还可以填写一些大略的描述信息(summary)或者解释该主主法的一段长篇大论(description)
<?php/ @SWG\Get( path=\公众/persons\公众, summary=\公众获取一些人\公众, description=\公众返回包含所有人的列表。\公众 )/
这样一来，我们调 get https://tcmapi.emao.com/v1/persons 方法就能获取一个用户信息列表了。
2.2.3 定义相应 (response) 类型
对付每个方法（或操作），我们都可以在相应(responses)中添加任意的 HTTP状态码（比如 200 OK 或者 404 Not Found等）。这个例子中我们添加上 200 的相应：
<?php/ @SWG\Response( response=200, description=\公众一个用户列表\公众 )/
2.2.4 定义相应内容
get /persons这个接口返回一组用户信息，我们通过相应中的模式（schema）属性来描述清楚详细的返回内容。
一组用户信息便是一个用户信息工具的数组（array），每一个数组元素则是一个用户信息工具（object），该工具包含三个string类型的属性：姓氏、名字、用户名，个顶用户名必须供应（required）。
<?php/ @SWG\Schema( type=\"大众array\"大众, @SWG\Items( required={\"大众username\"大众}, @SWG\Property( property=\公众firstName\公众, type=\"大众string\公众, description=\公众firstName\公众 ), @SWG\Property( property=\公众lastName\"大众, type=\"大众string\"大众, description=\"大众lastName\"大众 ), @SWG\Property( property=\"大众username\"大众, type=\"大众string\"大众, description=\"大众username\公众 ) ) )/
2.3 定义 要求参数 （query parameteers）
用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加要求参数来实现。
<?php/ @SWG\Parameter( name=\"大众pageSize\公众, in=\"大众query\"大众, description=\公众Number of persons returned\"大众, type=\"大众integer\公众 ), @SWG\Parameter( name=\"大众pageNumber\"大众, in=\"大众query\"大众, description=\"大众Page number\"大众, type=\"大众integer\公众 )/
2.3.1 在 get 方法中增加要求参数
<?php/ @SWG\Get( path=\公众/persons\公众, summary=\"大众获取一些人\"大众, description=\公众返回包含所有人的列表。\"大众, @SWG\Parameter() )/
2.3.2 添加分页参数
在参数列表中，我们添加两个名字（name）分别叫做 pageSize和pageNumber的整型（integer）参数，并作大略描述：
<?php/ @SWG\Get( path=\"大众/persons\公众, summary=\"大众获取一些人\公众, description=\公众返回包含所有人的列表。\"大众, @SWG\Parameter( name=\"大众pageSize\"大众, in=\"大众query\公众, description=\公众Number of persons returned\"大众, type=\公众integer\"大众 ), @SWG\Parameter( name=\"大众pageNumber\"大众, in=\公众query\"大众, description=\"大众Page number\"大众, type=\"大众integer\"大众 ) )/
这样一来，消费者就可以通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息（不超过20条）了。
2.4 定义 路径参数 （path parameter）
有时候我们想要根据用户名来查找用户信息，这时我们须要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。把稳，{username} 是在要求路径中的参数。
<?php/ @SWG\Get( path=\"大众/persons/{username}\"大众, summary=\公众获取一些人\公众, description=\公众返回包含所有人的列表。\公众, @SWG\Parameter( name=\公众username\"大众, in=\"大众path\"大众, required=\"大众true\公众 description=\公众The person's username\"大众, type=\"大众string\"大众 ) )/
2.4.1 添加一个 get /persons/{username} 操作
首先我们在 /persons 路径后面，增加一个 /persons/{username} 的路径，并定义一个 get （操作）方法。
<?php/ @SWG\Get( path=\"大众/persons/{username}\"大众, summary=\"大众Gets a person\"大众, description=\公众Returns a single person for its username\公众 )/
2.4.2 定义路径参数 username
由于 {username} 是路径参数，我们须要先像要求参数一样将它添加到 parameters 属性中，把稳名称该当同上面大括号（ { } ） 里面的名称同等。并通过 in 这个属性，来表示它是一个路径（path）参数。
<?php/ @SWG\Parameter( name=\"大众username\"大众, in=\"大众path\公众, required=\"大众true\公众 description=\"大众The person's username\公众, type=\"大众string\公众 )/
定义路径参数时很随意马虎涌现的问题便是忘却：required: true，Swagger的自动完成功能中没有包含这个属性定义。 如果没有写 require 属性，默认值是 false，也便是说 username 参数时可选的。可事实上，作为路径参数，它是必需的。
2.4.3 定义相应
别忘了获取单个用户信息也须要填写 200 相应，相应体的内容便是之前描述过的用户信息（用户信息列表中的一个元素）：
<?php/ @SWG\Response( response=200, description=\"大众A Person\公众, @SWG\Schema( required={\"大众username\公众}, @SWG\Property( property=\"大众firstName\公众, type=\公众string\"大众 ), @SWG\Property( property=\"大众lastName\公众, type=\"大众string\"大众 ), @SWG\Property( property=\公众username\"大众, type=\"大众string\"大众 ) ) )/
当然，API的供应者会对 username 进行校验，如果查无此人，该当返回 404 的非常状态。以是我们再加上 404 状态的相应：
<?php/ @SWG\Response( response=404, description=\公众The Person does not exists.\"大众 )/
