这篇“Laravel Swagger怎么使用”文章的知识点大部分人都不太理解,所以小编给大家总结了以下内容,内容详细,步骤清晰,具有一定的借鉴价值,希望大家阅读完这篇文章能有所收获,下面我们一起来看看这篇“Laravel Swagger怎么使用”文章吧。
swagger太辣鸡了?
本教程是基于Laravel 生成swagger 为例子,其实这个东西和语言或者和框架基本没啥区别,因为都是用的公用的json ,通过程序扫描swagger预先规定的“语言”,生成结构存入json中,通过 swagger ui 展现出来(或者自己开发)。
对于php开发人员来说,有大部分同学很不喜欢swagger。 因为这个看上去写起来好麻烦啊,一想到分分钟用php写完的代码,写swagger要写10分钟,心里就抵触这个东西。
身边有Java开发的同学就知道他们很大一部分都用swagger,因为java要维护数据结构,而且swagger在java整合得更灵活。
这个时候java如果看到有php 说swagger反人类的东西,太麻烦了,上古时代的产物。那身边的java朋友会心里窃喜,这么好用的东西都不用,还说php是世界上最好的语言。
我为啥用swagger
最近在写自动生成代码,其实现在Laravel 很多自动生成CURD的。比如像laravel-admin
,一条命令生成CURD,但是生成之后,数据看上去很冷。 比如有一些字段不需要显示,有一些是要select关联枚举的,有一些是 hasMany
的,还有 overtrue(正超)的api脚手架也挺好的
所以swaager也可以根据业务需求写自动化生成
L5-Swagger
安装:
composer require "darkaonline/l5-swagger"
使用:
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"php artisan l5-swagger:generate
填写下面例子生成之后再访问
/api/documentation
@OA\Info 为必须
例子
get 请求
如果要匹配path中的数值则 in path 查询 in query
POST 请求
文件上传参数
* @OA\RequestBody( * @OA\MediaType( * mediaType="multipart/form-data", * @OA\Schema( * type="object", * @OA\Property( * property="file", * type="file", * ), * ), * ) * ),
传入为枚举
* @OA\Parameter( * name="status", * in="query", * description="状态", * required=true, * explode=true, * @OA\Schema( * type="array", * default="available", * @OA\Items( * type="string", * enum = {"available", "pending", "sold"}, * ) * ) * ),
Body 为Json 方式提交
* @OA\RequestBody( * @OA\MediaType( * mediaType="application/json", * @OA\Schema( * @OA\Property( * property="id", * type="string" * ), * @OA\Property( * property="name", * type="string" * ), * example={"id": 10, "name": "Jessica Smith"} * ) * ) * ),
使用结构Schema作为请求参数
* @OA\RequestBody( * description="order placed for purchasing th pet", * required=true, * @OA\JsonContent(ref="#/components/schemas/UserModel") * ),
Schema的使用
枚举
一个枚举单独创建一个Schema
映射到模型中的具体字段
* @OA\Property( * property="status", * ref="#/components/schemas/product_status" * ),
这样前端开发者就可以
关联模型
和枚举差不多,通过一个Property关联模型
* @OA\Property( * property="user_detail", * ref="#/components/schemas/UserModel2" * ),
关联模型和枚举,可以自动生成请求的参数和,返回的结构
返回为模型结构
* @OA\Response( * response=200, * description="successful operation", * @OA\JsonContent( * type="array", * @OA\Items(ref="#/components/schemas/UserModel"), * @OA\Items(ref="#/components/schemas/UserModel2") * ) * ),
就比如那天前端小妹跟你说,哥哥,支付状态3代表什么,可能你很快的说出了是某某状态,但是问你11是啥状态,人都要沙雕了。
通过swagger 的Schema 能让前端人员摸清后端的结构信息
多个合并Schema
验证提供outh3 和apikey 两种方式,在存放全局配置中写入(也可以任意目录中)
在接口中添加
security={{"api_key": {}}},
这时,swagger Ui 会出现一个锁一样的东西
可以输入自己的token,请求的时候会带上token
可能遇到的问题
线上环境如果访问不了,可能是你nginx 配置的问题,因为,laravel-swagger 是通过file_content_get() 的方式 echo 输出js 的。而你的nginx 配置判断,如果是 .js 或者css 是静态文件,所以到不了index.php ,更执行不了 file_content_get 函数了。可以参考nginx 配置:
charset utf-8;client_max_body_size 128M;location / {try_files $uri $uri/ /index.php$is_args$args;}location ~ \.php$ {include fastcgi_params;fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;fastcgi_pass php74:9000 这个换成你自己的;try_files $uri =404;}
以上就是关于“Laravel Swagger怎么使用”这篇文章的内容,相信大家都有了一定的了解,希望小编分享的内容对大家有帮助,若想了解更多相关的知识内容,请关注编程网行业资讯频道。