swagger使用说明

1年前

安装swagger-php项目

这个项目可以用php的方式来swagger语法

composer require zircote/swagger-php

安装l5-swagger

这个项目可以让我们很便捷的使用swagger-ui,还有自动刷新功能呢..很赞 👍

当然也建议看下github的文档.说的还是很详细了

composer require "darkaonline/l5-swagger:5.5.*"

自动发布,生成ui模板

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

初始化

php artisan l5-swagger:generate

配置自动刷新

因为默认是不刷新的,那么我们在.env里面配置

L5_SWAGGER_GENERATE_ALWAYS=true

这点对文档编写调试很有帮助

公共配置

请求块说明

 * @SWG\Get(path="/xia-mi/music/{music}/lyric",
 *   tags={"虾米音乐"},
 *   summary="获取歌词",
 *   description="只能获取到原文歌词",
 *   operationId="getMyData",
 *   produces={"application/json"},
  • SWG\Get : Get请求,还有SWG/Post....等到
  • tags : tag分类同一种tag展示的时候会在一起
  • summary : 这个不知道
  • description : 这个是对接口的描述
  • operationId : 这个是针对这个接口的id,如果你两个接口设置成一样,你点其中一个,两个都会打开..所以这里建议唯一
  • produces : 数据格式吧..这个不知道

参数块说明

 *     @SWG\Parameter(
 *         description="ID of pet to fetch",
 *         format="int64",
 *         in="path",
 *         name="id",
 *         required=true,
 *         type="integer",
 *         default=2069544
 *     ),

description

参数描述

format

这个还不知道

in

  • query : 参数用在get query中
  • header : 参数用在header中
  • path : 用在路由中一般替换{id}
  • formData : 用于formData
  • body : 用于body

name

参数名称

required

是否是必须参数

type

参数类型

default

参数默认值

未解决的问题

  • 请求失败ui的response那里并不展示响应结果
  • 如何json高亮
  • 如何复用@SWG\Response
  • 如何在ui上展示正确的响应数据格式

问题

一直只发送option请求点这里看issue

请支持跨域

参考文章