• 技术文章 >php框架 >Laravel

    详细了解Laravel Swagger的使用

    长期闲置长期闲置2022-04-11 20:54:10转载842
    本篇文章给大家带来了关于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"}
         *             )
         *         )
         *     ),

    在这里插入图片描述

    使用结构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"
     *      ),

    关联模型和枚举,可以自动生成请求的参数和,返回的结构
    在这里插入图片描述

    返回为模型结构

         *     @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

    /**
     * @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 会出现一个锁一样的东西

    在这里插入图片描述

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

    在这里插入图片描述
    可以结合 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视频教程

    以上就是详细了解Laravel Swagger的使用的详细内容,更多请关注php中文网其它相关文章!

    声明:本文转载于:CSDN,如有侵犯,请联系admin@php.cn删除
    专题推荐:Laravel
    上一篇:归纳整理常见的laravel面试题 下一篇:实例详解Laravel事件监听
    20期PHP线上班

    相关文章推荐

    • 【活动】充值PHP中文网VIP即送云服务器• Laravel8中怎么优化数据库查询?18 个优化建议分享• laravel为什么用队列• laravel中ioc控制反转是什么• laravel门面是什么• 归纳Laravel 9.5版本的新增、修复和改变!
    1/1

    PHP中文网