1.要想使用swagger需要先在项目中进行配置：
以下代码的意思可以通过在专门的php文件中写入，然后再更新版本的时候可以直接更改该文件下的版本号，以及可以在这里直接设置header头的参数，这里的必须参数以签名、时间戳、用户id为例，非必须参数以版本为例；
/**
* @SWG\Info(
* title="***接口文档",
* version="2.0.0"
* )
*
* @SWG\Swagger(
* schemes={"http"}, //实用的协议类型
* swagger="2.0", //使用的是2.0的swagger版本
* host="", //要访问的链接地址
* basePath="/",
* consumes={"application/x-www-form-urlencoded"}
* )
*
* @SWG\Parameter(
* parameter="HeaderSign",
* name="x-access-sign",
* type="string",
* in="header",
* required=true,
* description="签名"
* )
*
* @SWG\Parameter(
* parameter="HeaderTime",
* name="x-access-time",
* type="string",
* in="header",
* required=true,
* description="10位Unix时间戳"
* )
*
* @SWG\Parameter(
* parameter="HeaderUid",
* name="uid",
* type="integer",
* in="header",
* required=true,
* description="用户ID"
* )
*
* @SWG\Parameter(
* parameter="HeaderVersion",
* name="x-access-version",
* type="string",
* in="header",
* required=false,
* description="版本号"
* )
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
的请求方式有get、post、put、delete四种方式，下面看一下各种请求的请求实例以及效果吧
1》首先是get请求,一下是两种get请求的不同格式的写法
/**
* @SWG\Get(
* path="/guide/{position}",
* tags={"其他"}, //swagger上的标签名
* summary="获取***信息", //概要，摘要
* description="获取***信息", //接口的详细描述
* @SWG\Parameter(ref="#/parameters/HeaderSign"),
* @SWG\Parameter(ref="#/parameters/HeaderTime"),
* @SWG\Parameter(ref="#/parameters/HeaderUid"),
* @SWG\Parameter(ref="#/parameters/HeaderVersion"),
* @SWG\Parameter(
* name="position",
* type="string",
* in="path",
* required=true,
* description="位置（）",
* format="string",
* ),
* @SWG\Parameter(
* name="os",
* type="string",
* in="path",
* required=true,
* description="版本(ios,android)",
* format="string"
* ),
* @SWG\Response(
* response="200",
* description="请求成功.",
* @SWG\Schema(
* type="object",
* required= {"id","name","type","img","appid","path","details_img"}, //因为在这里是required，注意最下面有几个请求数据这里对应的写几个
* @SWG\Property(
* property="id",type="int",description="id",example=155
* ),
* @SWG\Property(
* property="name",type="string",description="name",example="测试"
* ),
* @SWG\Property(
* property="type",type="integer",description="跳转类型",example="1"
* ),
* @SWG\Property(
* property="img",type="string",description="img",example="/mis/"
* ),
* @SWG\Property(
* property="appid",type="string",description="appid",example="wxdc93d68845c52efb"
* ),
* @SWG\Property(
* property="path",type="string",description="path",example="%2Fpages%2Fhome%2Fhome%3Futm_source%3Dsside%26templateId%3D348"
* ),
* @SWG\Property(
* property="details_img",type="string",description="details_img",example="/mis/"
* ),
* )
* ),
* @SWG\Response(
* response="400",
* description="uid必须"
* ),
* @SWG\Response(
* response="401",
* description="用户验证失败."
* ),
* @SWG\Response(
* response="403",
* description="验签失败."
* ),
* @SWG\Response(
* response="500",
* description="服务内部错误."
* )
* )
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 72
- 73
- 74
/**
* @SWG\Get(path="/user/info",tags={"swg"},summary="用户信息",description="永固的个人信息",
* @SWG\Parameter(ref="#/parameters/HeaderSign"),
* @SWG\Parameter(ref="#/parameters/HeaderTime"),
* @SWG\Parameter(ref="#/parameters/HeaderVersion"),
* @SWG\Parameter(ref="#/parameters/UID"),
* @SWG\Parameter(name="id", in="query", type="integer", required=false, description="用户ID"),
* @SWG\Response(response="200",description="请求成功.",
* @SWG\Schema(type="object",
* @SWG\Property(property="code", type="integer", description="状态码", example=200),
* @SWG\Property(property="message", type="string", description="提示信息", example="OK"),
* @SWG\Property(property="time", type="integer", description="系统时间戳", example=1574830121),
* @SWG\Property(property="data", type="object",
* @SWG\Property(property="user_info", type="array",
* @SWG\Items(type="object",
* @SWG\Property(property="uid", type="integer", description="用户ID", example=100),
* @SWG\Property(property="gender", type="integer", description="性别（0:未知 1:男 2:女）", example=1),
* @SWG\Property(property="nickname", type="string", description="昵称", example="马栏山二锅头"),
* @SWG\Property(property="tags", type="array",
* @SWG\Items(type="object",
* @SWG\Property(property="id", type="integer",description="标签ID"),
* @SWG\Property(property="content", type="string",description="标签名称"),
* ),
* ),
* ),
* ),
* @SWG\Property(property="follow_status", type="integer", description="关注状态 0 未关注 1已关注 2互相关注 3回关", example=1),
* @SWG\Property(property="guest_user", type="array",
* @SWG\Items(type="object",
* @SWG\Property(property="uid", type="integer", description="用户ID", example=100),
* @SWG\Property(property="nickname", type="string",description="昵称",example="月亮"),
* @SWG\Property(property="avatarurl", type="string",description="头像",example="/avarurl/"),
* @SWG\Property(property="gender", type="integer",description="性别",example=1),
* ),
* ),
* ),
* ),
* ),
* @SWG\Response(response="412",description="签名验证失败"),
* @SWG\Response(response="422",description="参数校验失败"),
* @SWG\Response(response="500",description="服务内部错误")
* )
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
请求示例：上面的格式响应出来的是一个列表，响应示例，
如果单纯的响应一个code的话可以使用下面的格式
代码：
* @SWG\Response(
* response="200",
* description="请求成功"
* ),
- 1
- 2
- 3
- 4
请求结果：
2》post请求
/**
* @SWG\Post(
* path="/pic/like",
* tags={"图片社区"},
* summary="点赞",
* description="点赞",
* @SWG\Parameter(ref="#/parameters/HeaderSign"),
* @SWG\Parameter(ref="#/parameters/HeaderTime"),
* @SWG\Parameter(ref="#/parameters/HeaderUid"),
* @SWG\Parameter(
* name="id",
* type="integer",
* in="formData",
* required=true,
* description="帖子id",
* format="int"
* ),
*
* @SWG\Parameter(
* name="pic_uid",
* type="integer",
* in="formData",
* required=true,
* description="发帖用户id",
* format="int"
* ),
* @SWG\Response(
* response="200",
* description="请求成功",
* @SWG\Schema(
* type="object",
* required={"lists"},
* @SWG\Property(property="lists", type="array",
* @SWG\Items(type="object",
* @SWG\Property(property="goods_id",type="integer",description="产品id",example=8),
* @SWG\Property(property="img",type="string",description="****",example="url"),
* @SWG\Property(property="vote",type="integer",description="票数",example=10),
* @SWG\Property(property="money",type="integer",description="价格*100",example=4390),
* @SWG\Property(property="special", type="string",description="****",example="正常；特殊"),
* )
* ),
* ),
* )
* ),
* @SWG\Response(
* response="400",
* description="uid、pic_uid必须"
* ),
* @SWG\Response(
* response="401",
* description="用户验证失败."
* ),
* @SWG\Response(
* response="403",
* description="验签失败."
* ),
* @SWG\Response(
* response="500",
* description="服务内部错误."
* )
* )
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
请求示例：
3》put请求
* @SWG\Put(
* path="/add_num",
* tags={"swg"},
* summary="数量",
* description="添加数量",
* @SWG\Parameter(ref="#/parameters/HeaderSign"),
* @SWG\Parameter(ref="#/parameters/HeaderTime"),
* @SWG\Parameter(ref="#/parameters/HeaderUid"),
* @SWG\Parameter(
* name="num",
* type="integer",
* in="formData",
* required="true",
* description="数量",
* format="int"
* ),
* @SWG\Response(
* response="200",
* description="请求成功.",
* @SWG\Schema(
* type="object",
* required={"gold"},
* @SWG\Property(
* property="gold",
* type="int",
* description="数量",
* example=50
* )
* )
* ),
* @SWG\Response(
* response="400",
* description="uid必须."
* ),
* @SWG\Response(
* response="401",
* description="用户验证失败."
* ),
* @SWG\Response(
* response="403",
* description="验签失败."
* ),
* @SWG\Response(
* response="500",
* description="服务内部错误."
* )
* )
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
响应结果示例：
4》delete请求
/**
* @SWG\Delete(
* path="/pic/del/{id}",
* tags={"图片社区"},
* summary="删除图片",
* description="删除图片",
* @SWG\Parameter(ref="#/parameters/HeaderSign"),
* @SWG\Parameter(ref="#/parameters/HeaderTime"),
* @SWG\Parameter(ref="#/parameters/HeaderUid"),
* @SWG\Parameter(
* name="id",
* type="integer",
* in="path",
* required=true,
* description="id",
* format="int"
* ),
* @SWG\Response(
* response=200,
* description="请求成功",
* @SWG\Schema(
* type="object",
* required={"list"},
* @SWG\Property(property="list", type="array",
* @SWG\Items(type="object",
* @SWG\Property(property="id",type="integer",description="id",example=23124),
* @SWG\Property(property="uid",type="integer",description="用户id",example=134),
* @SWG\Property(property="nickname",type="string",description="昵称",example="我最美"),
* @SWG\Property(property="avatarurl",type="string",description="头像",example="/mmopen/vi_32/Q0j4TwGTfTKlw8dFYtNVKP9ibuc7lT2DHz0eFxXzI2L3ibnJJyW"),
* @SWG\Property(property="img_url", type="array",description="图片url",
* @SWG\items(
* type="string",
* example=""
* )
* ),
* @SWG\Property(property="img_size", type="array",description="图片尺寸",
* @SWG\items(
* type="string",
* example="810,1080"
* )
* ),
* @SWG\Property(property="rank",type="integer",description="排名",example=1),
* @SWG\Property(property="like",type="integer",description="数量",example=1024),
* @SWG\Property(property="create_time",type="string",description="时间",example="2019-07-25 09:49:37"),
* @SWG\Property(property="vip",type="integer",description="标识",example=0)
* ),
* ),
* ),
* )
* ),
* @SWG\Response(
* response="400",
* description="uid必须"
* ),
* @SWG\Response(
* response="401",
* description="用户验证失败."
* ),
* @SWG\Response(
* response="403",
* description="验签失败."
* ),
* @SWG\Response(
* response="500",
* description="服务内部错误."
* )
* )
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
请求结果示例：
总结说明： @SWG\Parameter()为请求的参数，需要注意一下格式；@SWG\Response()为响应的参数，最后请求的时候是列表还是一个参数，请求的格式和get的列表和参数的格式是一样的；
3》需要执行命令 ：
以下命令可以直接生成一个文档并把文档当到指定位置
swagger文档配置位置 swagger文档的位置 -o 要把生成的文档写入的文件位置（例如 /home/wwwroot/api_doc/swagger-php/bin/swagger /home/wwwroot/test/application/index/controller -o /home/wwroot/api_doc/）
最后访问文档
或者也可以用以下命令直接生成文档swagger-php/bin/swagger生成 ,
4》参数描述 (@SWGParameter) 常用字段:
name - string
参数名. 通过路径传参(in 取值 “path”)时有注意事项,没用到,懒得看了…
in - string
参数从何处来. 必填. 取值仅限: “query”, “header”, “path”, “formData”, “body”
description - string
参数描述. 最好别太长
type - string
参数类型. 取值仅限: “string”, “number”, “integer”, “boolean”, “array”, “file”
required - boolean
参数是否必须. 通过路径传参(in 取值 “path”)时必须为 true；in取值为formData时可为true可为false；
default - *
默认值. 在你打算把参数通过 path 传递时规矩挺多,我没用到.用到的可以自己看下文档
5》接口描述 (@SWGGet, @SWGPost 等) 常用字段:
summary - string
接口的简要介绍,会显示在接口标头上,不能超过120个字符
description - string
接口的详细介绍
externalDocs - string
外部文档链接
operationId - string
全局唯一的接口标识
consumes - [string]
接口接收的MIME类型
produces - [string]
接口返回的MIME类型,如 application/json
schemes - [string]
接口所支持的协议,取值仅限: “http”, “https”, “ws”, “wss”
parameters - [Parameter Object | Reference Object]
参数列表
------------------------------使用过程中可能遇到的错误--------------------------------
如果curl中出现这个错误：curl -X GET “” -H “accept: application/json” -H “x-access-sign: 11111111” -H “x-access-time: 2019” -d “uid: 5”，说明你的请求方式有问题，-d指的是post请求，而你上面用的是get请求，关于请求方式如何修改，可以修改文档中的参数，其中有一个“in”的参数代表的是get还是post的请求，如果是get请求应改成 in=“path”,如果是post请求，应改成in=“formData”！！！
自认为写的比较详细了，希望能够帮助到您！！！！