1. 安装Composer


确认Composer是否已安装，cmd窗口输入命令：


composer -V


如果能看到版本号信息，说明Composer已经安装，如图：






否则请自行下载安装，下载地址：


https://getcomposer.org/download/






2. 安装swagger-php


cmd窗口中，切换到TP5项目的根目录，输入命令：


composer require zircote/swagger-php






安装成功后，vendor目录下会自动生成zircote/swagger-php子目录，如图：






3. 初始化swagger


项目根目录下新建一个子目录，名称为swagger-docs，然后切换到项目根目录下，执行命令：


php vendor/zircote/swagger-php/bin/swagger vendor/zircote/swagger-php/Examples -o swagger-docs/swagger.json


成功后，目录结构如下：






4. 下载swagger-ui


在swagger-ui官网下载静态页面，把静态页面放到thinkphp框架目录里。


https://swagger.io/tools/swagger-ui/






或者直接通过github下载也行，下载地址：


https://github.com/swagger-api/swagger-ui






5. 集成swagger-ui到项目中


在TP5项目的public目录下，新建一个子目录，名称为swagger，然后将swagger-ui-master.zip压缩包中dist目录下的文件复制到swagger目录下，如图：






然后，修改swagger目录下的index.html文件，将里面的url参数修改为swagger.json文件（第3步中初始化生成）的访问地址即可，如图：






此时，如果访问http://local.tpmanager:8090/public/swagger这个链接，将会看到如下界面：






表示swagger已经搭建成功了，只不过展示的是示例文档。


注意：以上的配置，其实是一个单文档配置，所有的接口都会在一个json文件中，如果接口比较多的话，可以使用多文档配置，给文档进行分类。


多文档的配置方式如下：


同样是修改swagger目录下的index.html文件，将url参数注释掉，然后增加urls参数，内容如下：


urls:[
 
    {url:"http://local.tpmanager:8090/swagger-docs/swagger.json",name:"前端文档"},
 
    {url:"http://local.tpmanager:8090/swagger-docs/swagger-admin.json",name:"后端文档"}
 
],
完整的内容如下图：






6. 编写自己的文档接口


6.1 编写整个项目的文档概述


随便找一个Controller的类文件，在其上面添加如下注解：


/**
* @SWG\\Swagger(
* @SWG\\Info(
* title="API文档",
* version="版本1.0",
* description="本文档仅限于测试"
* )
* )
*/
如图：






6.2 编写具体的接口文档


在Controller文件的方法上添加如下注解：


/**
* @SWG\\Post(
* path="/api/article",
* tags={"文章管理"},
* summary="文章列表",
* description="显示页面",
* @SWG\\Parameter(name="token", type="string", in="header", description="token"),
* @SWG\\Parameter(name="page", type="integer", in="formData", description="页码",required=false),
* @SWG\\Parameter(name="limit", type="integer", in="formData", description="行数",required=false),
* @SWG\\Response(response="200", description="The User")
* )
*/
文档编写好后，我们需要重新执行初始化命令：


php vendor/zircote/swagger-php/bin/swagger application/api/controller -o swagger-docs/swagger.json


注意：该命令需要切换到项目根目录下执行，其中的application/api/controller，就是我们项目中控制器文件的目录，swagger-docs/swagger.json是初始化时创建的swagger.json文件。


参数说明


@SWG\\Post 表示是一个Post请求


    tags 接口标签名称， 标签可用于对接口进行逻辑分组


    summary 接口名称


    description 接口详细描述


    path 路由信息，即请求路径


@SWG\\Parameter 用来设置请求参数相关信息


name 参数名称


type 参数类型，可选值有：


        string、number、integer、boolean、array、或 file


in 参数的位置，即请求方式，可选值有：


        formData 表示是 post 请求的数据


        query 表示带在 url 之后的参数，即get请求的参数


        path 表示请求路径上的参数


        body 表示是一个 raw 数据请求


        header 表示带在 header 信息中的参数


description 参数描述


required 定义该参数是否必须，可选值：true 或者 false


default 参数的默认值


@SWG\\Response 设置返回信息


response 通常为状态码


description 返回描述


7. 访问swagger


打开浏览器，在地址栏中输入http://local.tpmanager:8090/public/swagger


即可看到如下界面：


单文档配置






多文档配置




————————————————
版权声明：本文为CSDN博主「木鱼大叔」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/tdcqfyl/article/details/109673808