- 这里以TP5(thinkPHP5)为例子
-
背景(先说一些废话)
Swagger 是一个简单但功能强大的 API 表达工具。它具有地球上最大的 API 工具生态系统,数以千计的开发人员,使用几乎所有的现代编程语言,都在支持和使用 Swagger。使用 Swagger 生成 API,我们可以得到交互式文档,自动生成代码的 SDK 以及 API 的发现特性等。
OpenAPI 规范是 Linux 基金会的一个项目,试图通过定义一种用来描述 API 格式或 API 定义的语言,来规范 RESTful 服务开发过程。OpenAPI 规范帮助我们描述一个 API 的基本信息
而swagger就是使用openapi的规范使用工具
OpenAPI = 规范
Swagger = 实现规范的工具 -
为何要使用 OpenAPI 规范?
OpenAPI 规范这类 API 定义语言能够帮助你更简单、快速的表述 API,尤其是在 API 的设计阶段作用特别突出
根据 OpenAPI 规范编写的二进制文本文件,能够像代码一样用任何 VCS 工具管理起来
一旦编写完成,API 文档可以作为:
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用,比如开放平台开发者的手册... -
首先项目安装swagger
- composer安装swagger-php (我另一篇文章写了php安装swagger+swaggerUI 也有写到)
为了方便 我使用了一些插件
1. phpstrom插件安装
PHP Annotation
swagger
2. composer安装swagger-php
composer require zircote/swagger-php
- 数据格式编码(以下是自己写的一点示例)
示例
/**
* @author 才不是小小喵
* @SWG\Post(
* path="/testThree",
* consumes={"multipart/form-data"},
* tags={"测试分类"},
* summary="这是测试第四个接口",
* description="这是第四个接口的描述",
* @SWG\Parameter( name="id",in="formData",description="这是请求参数描述(才不是小小喵)",required=true, type="integer",
* default="1", ),
* @SWG\Response(
* response="200",
* description="返回结果"
* )
* )
*/
public function testThree(){}
示例说明
@SWG\Post 声明接口类型
@SWG\Parameter 接口参数
@SWG\Response 接口返回
示例图片:
image.png
- 生成swagger.json
项目下运行命令
php vendor\zircote\swagger-php\bin\swagger application\index\controller -o application\swagger-docs
- 上传swagger.json到yapi
安装 yapi-cli (直接命令导入接口)
##官方安装命令
npm install -g yapi-cli --registry https://registry.npm.taobao.org
新建一个配置文件
目录下新建配置文件yapi-import.json (默认必须用这个名字)
以下是yapi-import.json内容
{
"type": "swagger",
"token": " ad71309a4557bdb540ffc2c40278071006ba24343ac9c5e39c3aa05e42b34a79",
"file": " ./application/swagger-docs/swagger.json ",
"merge": "good",
"server": " http://192.168.0.199:23009/ "
}
执行导入命令
yapi import
命令解释:
type 是数据数据方式 目前官方只支持 swagger
token 是项目token 在 Yapi项目 设置 > token配置
file 是 swagger.json 接口目录地址 或者URL
merge 导入旧的接口策略 默认使用智能模式 一共有 "normal"(普通模式) "good"(智能合并) "merge"(完全覆盖) 三种模式(swagger自动同步 其实也是一样)
server 是yapi服务器地址
-
PS:token地址 (swagger自动同步其实也可以 这篇文章说的是手动同步)
image.png
网友评论