详细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

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;
}

本文出至：学新通