编程学习网 > PHP技术 > laravel > 使用 laravel-Swagger 编写接口文档
2021
07-22

使用 laravel-Swagger 编写接口文档

Swagger 文档管理

快速编写你的 RESTFUL API 接口文档工具,通过注释定义接口和模型,可以和代码文件放置一起,也可以单独文件存放。

优势

通过代码注解定义文档,更容易保持代码文档的一致性

模型复用,减少文档冗余,带来更可靠的文档

提供客户端访问接口,可以直接调试接口,不需要第三方工具进行调用测试接口

支持权限认证,等功能

laravel Swagger 扩展

composer require darkaonline/l5-swagger

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

将会生成配置文件 l5-swagger.php,其中需要注意的配置项


routes.api 默认值为 api/documentation Swagger 文档系统访问路由

routes.docs Swagger 解析注释生成文档 JSON 文件的存储路径

paths.annotations 有效注释的路径配置,默认 base_path('app') 应用路径

generate_always 测试环境应该开启这个配置,每次访问都会自动解析注释生成最新的文档

swagger_version 这个默认为 2.0 , 建议修改为 3.0

下文所有的注释内容,需要存在于 paths.annotations 路径下。


接口版本

@OA\Info 定义接口版本,标题,描述,以及作者信息。


/**

* @OA\Info(

*      version="1.0",

*      title="用户管理",

*      description="用户模块接口",

*      @OA\Contact(

*          name="PHP 开发支持",

*          email="dreamhelingfeng@gmail.com"

*      )

* )

*/


接口请求方式与请求路径

@OA\Get,@OA\Post 定义接口请求方式


示例:根据USER_ID请求用户详情信息 /api/users/{user_id}

接口分组配置:tags,将会对接口归类


/**

 * @OA\Get(

 *   path="/api/users/{user_id}",

 *   summary="根据 ID 获取用户信息",

 *   tags={"用户管理"},

 *   @OA\Parameter(

 *     name="user_id",

 *     in="path",

 *     required=true,

 *     description="用户 ID",

 *     @OA\Schema(

 *        type="string"

 *     )

 *   ),

 *   @OA\Response(

 *     response=200,

 *     description="用户对象",

 *     @OA\JsonContent(ref="#/components/schemas/UserModel")

 *   )

 * )

 */


接口请求参数

通过 Swagger 可以定义三类参数,path,header,query


path, 参数存在 endponit 中,如,/users/{user_id}

header, 参数存在请求头部,如,token 用户校验令牌

query, 请求参数带在请求URL上,如,/users?nickname={nickname}


/**

 * @OA\Get(

 *   @OA\Parameter(

 *     name="user_id",

 *     in="path",

 *     required=true,

 *     description="用户 ID",

 *     @OA\Schema(

 *        type="string"

 *     )

 * )

 */


POST 提交表单,通常使用 application/json 方式,如,创建用户


@OA\Post

path=/users

/**

 *   @OA\RequestBody(

 *       @OA\MediaType(

 *           mediaType="application/json",

 *           @OA\Schema(ref="#/components/schemas/UserModel"),

 *           example={

 *              "username": "helingfeng", "age": "25"

 *           }

 *       )

 *   )

 */


Schema 模型定义

上面的注释中,多次引用 @OA\Schema(ref="#/components/schemas/UserModel")


/**

* @OA\Schema(

*      schema="UserModel",

*      required={"username", "age"},

*      @OA\Property(

*          property="username",

*          type="string",

*          description="用户名称"

*      ),

*      @OA\Property(

*          property="age",

*          type="int",

*          description="年龄"

*      )

* )

*/


Laravel-Swagger 会自动根据您的注释进行匹配


上传文件接口示例

定义一个接口,接收上传文件,并返回结果远程文件地址


接口定义:


/**

 * @OA\Post(

 *   path="/api/files/upload",

 *   summary="文件上传",

 *   tags={"文件上传"},

 *   @OA\RequestBody(

 *       @OA\MediaType(

 *           mediaType="multipart/form-data",

 *           @OA\Schema(

 *              required={"upload_file"},

 *              @OA\Property(

 *                  property="upload_file",

 *                  type="file",

 *                  description="上传文件"

 *              ),

 *           ),

 *       )

 *   ),

 *   @OA\Response(

 *     response=200,

 *     description="上传成功",

 *     @OA\JsonContent(ref="#/components/schemas/UploadFileModel")

 *   ),

 *   @OA\Response(

 *     response="default",

 *     description="error",

 *     @OA\JsonContent(ref="#/components/schemas/ErrorModel")

 *   )

 * )

 */


模型定义:


/**

* @OA\Schema(

*      schema="UploadFileModel",

*      @OA\Property(

*          property="file_name",

*          type="string",

*          description="文件名,不包含路径"

*      ),

*      @OA\Property(

*          property="file_path",

*          type="string",

*          description="文件路径"

*      ),

*      @OA\Property(

*          property="file_url",

*          type="string",

*          description="URL链接,用于展示"

*      ),

*      @OA\Property(

*          property="file_size",

*          type="string",

*          description="文件大小,单位B"

*      ),

*      @OA\Property(

*          property="extension",

*          type="string",

*          description="文件扩展名"

*      )

* )

*/



需要权限认证的接口

一般对外网开放的接口,需要添加权限控制,Swagger 提供很好的支持


在 l5-swagger.php 配置文件中添加, crypt-token 定义请求头部必须添加 token 作为权限校验令牌。


'security' => [

   /*

   |--------------------------------------------------------------------------

   | Examples of Security definitions

   |--------------------------------------------------------------------------

   */

   'crypt-token' => [ // Unique name of security

       'type' => 'apiKey', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".

       'description' => 'A short description for security scheme',

       'name' => 'token', // The name of the header or query parameter to be used.

       'in' => 'header', // The location of the API key. Valid values are "query" or "header".

   ],

]


接口注释中,添加对应的验证方式:


/**

 * security={

 *    {"crypt-token": {}}

 * },

 */
以上就是“使用 laravel-Swagger 编写接口文档”的详细内容,想要了解更多laravel教程欢迎关注编程学习网


扫码二维码 获取免费视频学习资料

Python编程学习

查 看2022高级编程视频教程免费获取