Swagger-php使用指南(自动化获取最新api生成文档)

1.首先swagger 的认识

先说什么是Swagger, Swagger的使用目的是方便优美的呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置, 前端直接看这个Swagger UI就可以, 方便项目管理和团队协作.

官网: http://swagger.io/

参数文档: https://github.com/swagger-api/swagger-ui#parameters

这东西咋用呢? 说白了就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件, 再通关Swagger前端来美化,整理JSON数据.

就是一个api的管理工具，一种规范，为后端和客户端做便利的一种工具。

2.安装 后端 也就是 swagger-PHP

    composer require zircote/swagger-php 

执行就可以了就下载下来了，然后项目根目录会增加一个vendor这里面就是所谓的 swagger-PHP

使用：

require("vendor/autoload.php");

$openapi = \OpenApi\scan('/path/to/project');

header('Content-Type: application/x-yaml');

echo $openapi->toYaml();

3.接下来就是怎么写注释 生成json 然后 ui 显示

会看到里面好多@SWG 这样的注释（参考最新的文档实例），这些就是文档啦，这个插件会自动提取这些注释然后生成一个json文件，然后ui 就可以 读取出来了。

4.生成json文件

方法1:  我这里是写了一个控制器/方法，直接访问方法名获取最新信息写入到swagger.json里，然后在重定向到页面，如图

方法2:  当然还有命令行的方法：

php /phpstudynew/www/swagger/vendor/zircote/swagger-php  /bin/swagger/phpstudynew/www/swagger/application/controllers -o  /phpstudynew/www/swagger/docs/json

-o前面是自动获取 整个文件夹下面所有的 注释，后面是生成的路径，也是ui访问的路径，这个默认好像是swagger.json就这样成功了

5.安装前端

swagger-ui下载 

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

下载之后找到dist目录复制到自己项目一个可以访问的位置, 打开index.html把其中的那一串url改成自己的, 比如http://localhost/yii2/swagger-docs/swagger.json

$(function() {

var url = window.location.search.match(/url=([^&]+)/);

if(url && url.length > 1) {        

url = decodeURIComponent(url[1]);      

}else{       

 url = "你生成的swagger.json文件位置";     

 }

然后访问了自己项目dist/index.html的页面,就出现下面的界面

简单写了下实现swagger的方法，还待学习，总之要看文档学着把文档把例子看好，很多博客可能有时间关系 文档都更新了，所以注释格式会出现错误的现象，所以一定最先去参考文档！。