福州网站建设>网站新闻>php技术

Swagger-PHP api文档详细基础教程

发布日期:2022-03-17浏览次数:98 来源:福州网站建设

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
php技术有关的文章
如果您有什么问题,欢迎咨询我们客服! 点击QQ咨询
欧美肥老太牲交大战