详细了解Laravel Swagger的使用

2022-05-15 0 1,013

本篇文章给大家带来了关于laravel的相关知识,其中主要介绍了Swagger使用的相关问题,下面一起来看一看基于Laravel 生成swagger 为例子,希望对大家有帮助。

详细了解Laravel Swagger的使用

【相关推荐:laravel视频教程】

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

https://github.com/DarkaOnLine/L5-Swagger

安装:

composer require "darkaonline/l5-swagger"

使用:

php artisan vendor:publish --provider "L5Swagger\\L5SwaggerServiceProvider"php artisan l5-swagger:generate

填写下面例子生成之后再访问

/api/documentation

@OA\\Info 为必须

例子

/** * @OA\\Info( *      version="1.0.0", *      title="L5 OpenApi", *      description="L5 Swagger OpenApi description", *      @OA\\Contact( *          email="darius@matulionis.lt" *      ), *     @OA\\License( *         name="Apache 2.0", *         url="http://www.apache.org/licenses/LICENSE-2.0.html" *     ) * ) */

get 请求

如果要匹配path中的数值则 in path 查询 in query

/** * @OA\\Get( *      path="/projects/{id}", *      operationId="getProjectById", *      tags={"Projects"}, *      summary="Get project information", *      description="Returns project data", *      @OA\\Parameter( *          name="id", *          description="Project id", *          required=true, *          in="path", *          @OA\\Schema( *              type="integer" *          ) *      ), *      @OA\\Response( *          response=200, *          description="successful operation" *       ), *      @OA\\Response(response=400, description="Bad request"), *      @OA\\Response(response=404, description="Resource Not Found"), *      security={ *         { *             "oauth2_security_example": {"write:projects", "read:projects"} *         } *     }, * ) */

POST 请求

                  /**     * @OA\\Post(     *      path="/api/test/store",     *      operationId="api/test/store",     *      tags={"Test"},     *      summary="Test创建",     *      description="Test提交创建",     *      @OA\\Parameter(     *          name="id",     *          description="",     *          required=false,     *          in="query",     *      ),     *     @OA\\Response(     *         response=200,     *         description="successful operation",     *         @OA\\JsonContent(     *         ref="#/components/schemas/Test"     *         )     *     ),     *      @OA\\Response(response=400, description="Bad request"),     *      @OA\\Response(response=404, description="Resource Not Found"),     *      security={     *         {     *             "api_key":{}     *         }     *     },     * )     */

文件上传参数

     *     @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"}     *             )     *         )     *     ),

详细了解Laravel Swagger的使用

使用结构Schema作为请求参数

     *     @OA\\RequestBody(     *         description="order placed for purchasing th pet",     *         required=true,     *         @OA\\JsonContent(ref="#/components/schemas/UserModel")     *     ),

Schema的使用

/** * @OA\\Schema( *      schema="UserModel", *      required={"username", "age"}, *      @OA\\Property( *          property="username", *          format="string", *          description="用户名称", *          example="小廖", *      ), *      @OA\\Property( *          property="age", *          format="int", *          description="年龄", *          example=1, *          nullable=true, *      ) * ) */

枚举

一个枚举单独创建一个Schema

/** * @OA\\Schema( *   schema="product_status", *   type="string", *   description="The status of a product", *   enum={"available", "discontinued"}, *   default="available" * ) */

映射到模型中的具体字段

 *      @OA\\Property( *     property="status", *     ref="#/components/schemas/product_status" *      ),

这样前端开发者就可以

关联模型

和枚举差不多,通过一个Property关联模型

 *      @OA\\Property( *     property="user_detail", *     ref="#/components/schemas/UserModel2" *      ),

关联模型和枚举,可以自动生成请求的参数和,返回的结构
详细了解Laravel Swagger的使用

返回为模型结构

     *     @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 能让前端人员摸清后端的结构信息,比如:

详细了解Laravel Swagger的使用

各位,这些都可以自动化编程,自动生成的,工作效率不要太爽

多个合并Schema

/** * @OA\\Schema( *   schema="UserModel", *   allOf={ *     @OA\\Schema(ref="#/components/schemas/UserModel2"), *     @OA\\Schema( *       type="object", *       description="Represents an authenticated user", *       required={ *         "email", *         "role", *       }, *       additionalProperties=false, *       @OA\\Property( *         property="email", *         type="string", *         example="user@example.com", *         nullable=true, *       ), *     ) *   } * ) */

验证提供outh2 和apikey 两种方式,在存放全局配置中写入(也可以任意目录中)

/** * @OA\\SecurityScheme( *     type="apiKey", *     in="query", *     securityScheme="api_key", *     name="api_key" * ) */

在接口中添加

security={{"api_key": {}}},

这时,swagger Ui 会出现一个锁一样的东西

详细了解Laravel Swagger的使用

可以输入自己的token,请求的时候会带上token

详细了解Laravel Swagger的使用
可以结合 Laravel 的自带token验证,可以参考之前写的文章 Laravel guard 菊花守卫者

更多使用方法可以查看官网例子: https://github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0

可能遇到的问题

线上环境如果访问不了,可能是你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视频教程】

收藏 (0) 打赏

感谢您的支持,我会继续努力的!

打开微信/支付宝扫一扫,即可进行扫码打赏哦,分享从这里开始,精彩与您同在
点赞 (0)

【声明:根据2013年1月30日《计算机软件保护条例》2次修订第17条规定: 为了学习和研究软件内含的设计思想和原理,通过安装、显示、传输或者存 储软件等方式使用软件的,可以不经软件著作权人许可,不向其支付报酬! 鉴于此,也希望大家按此说明研究软件!】
本站所有源码尽量保证原汁原味,如有特殊情况会作出声明及标注,网站资源不做任何二次加密(原版加密除外,不影响程序使用的不会做解密处理),方便您更好的学习参考。 在您的能力范围内,为了大环境的良性发展,请尽可能的选择正版资源。如若本站内容侵犯了原著者的合法权益,可联系我们进行处理。

即刻码站__国内靠谱的站长资源下载平台 php教程 详细了解Laravel Swagger的使用 https://www.jike1995.com/36742.html

常见问题
  • 本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用
查看详情
  • 最常见的情况是下载不完整: 可对比下载完压缩包的与网盘上的容量,若小于网盘提示的容量则是这个原因。这是浏览器下载的bug,建议用百度
查看详情

相关文章

发表评论
暂无评论
官方客服团队

为您解决烦忧 - 24小时在线 专业服务