PHP项目swagger结合yapi命令生成接口文档

• 这里以TP5（thinkPHP5）为例子

1. 背景（先说一些废话）
   Swagger 是一个简单但功能强大的 API 表达工具。它具有地球上最大的 API 工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用 Swagger。使用 Swagger 生成 API，我们可以得到交互式文档，自动生成代码的 SDK 以及 API 的发现特性等。
   OpenAPI 规范是 Linux 基金会的一个项目，试图通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程。OpenAPI 规范帮助我们描述一个 API 的基本信息
   而swagger就是使用openapi的规范使用工具
   OpenAPI = 规范
   Swagger = 实现规范的工具

2. 为何要使用 OpenAPI 规范？
   OpenAPI 规范这类 API 定义语言能够帮助你更简单、快速的表述 API，尤其是在 API 的设计阶段作用特别突出
   根据 OpenAPI 规范编写的二进制文本文件，能够像代码一样用任何 VCS 工具管理起来
   一旦编写完成，API 文档可以作为：
   需求和系统特性描述的根据
   前后台查询、讨论、自测的基础
   部分或者全部代码自动生成的根据
   其他重要的作用，比如开放平台开发者的手册...

3. 首先项目安装swagger

• composer安装swagger-php (我另一篇文章写了php安装swagger+swaggerUI 也有写到)
  为了方便 我使用了一些插件

1. phpstrom插件安装
PHP Annotation
swagger
2. composer安装swagger-php
composer require zircote/swagger-php

4. 数据格式编码（以下是自己写的一点示例）
   示例

 /**
     * @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

5. 生成swagger.json
   项目下运行命令

php vendor\zircote\swagger-php\bin\swagger application\index\controller -o application\swagger-docs

6. 上传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