PHP如何使用Swagger生成好看的API文档
导读:本文共2809.5字符,通常情况下阅读需要9分钟。同时您也可以点击右侧朗读,来听本文内容。按键盘←(左) →(右) 方向键可以翻页。
摘要: 一、安装swagger-phpcomposerrequirezircote/swagger-phpswagger-php提供了命令行工具,所以可以全局安装,然后把工具的路径加到PATH里去。composerglobalrequirezircote/swagger-php然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到,... ...
目录
(为您整理了一些要点),点击可以直达。swagger-php提供了命令行工具,所以可以全局安装,然后把工具的路径加到PATH里去。
然后把zircote/swagger-php/bin 目录加到PATH里。这个东西本人用不到,就不研究了。
a)、生成一个控制器: SwaggerController
b)、添加一个方法: getJSON()
有的文章里写 \Swagger\scan(),但我这里报错,说找不到这个类。查了官方文档,要用 \OpenApi\Generator::scan()。有可能是新版本做了修改。
c)、设置路由
api.php 或者 web.php都行,路径不同而已。本人选择api.php。所以访问路径要加个前缀:/api。
d)、测试访问
访问 http://localhost:8000/api/swagger/json 如果看到页面正常输出json,说明配置成功了。不然就按错误提示一项项去修改吧。
GET方法
这里面:
in 表示该参数出现在哪里。 query的话就是用&拼在url后面; path 类似于 /api/data/search/{param} ; header就是包含在 request header里;cookie 自然是放在cookie里。
这个版本里formData, body这些都没有了。
required 看名字就知道 true是必填项,false是选填项。
POST方法
因为本人的前端代码post都是表单提交,所以这里的post方法要用@OA\RequestBody。
@OA\Parameter是参数,是可以放到url上,但是post的表单提交,数据是不出现在url上的。
@OA\MediaType 这个: x-www-form-urlencoded 表单提交;application/json 提交json格式的数据;multipart/form-data 文件上传;
这个是关联到一个已经定义好的schema上,省得使用相同数据的每个接口注释里都写一遍。
这里也可以单独写:
上面这样,有多少个参数就写多少个@OA\Property。这里的required是个数组,写在里面的都是必填项。
解压后,把目录里的dist目录,复制到laravel的public目录下面,改名为swagger-ui。文件名随便取,不冲突就行。
找开这个swagger-ui目录下的swagger-initializer.js,内容大概如下:
主要是改 url这项。改成前面设的路由地址。这里是 "/api/swagger/json"。完成后访问 http://localhost:8000/swagger-ui/ 就能看到swagger形成的api文档了。
PHP如何使用Swagger生成好看的API文档的详细内容,希望对您有所帮助,信息来源于网络。