Laravel swagger接口文档生成和管理
接口开发随着时间推移接口会越来越多，随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用
这里推荐swagger生成和管理接口文档，下面介绍基于laravel项目的swagger使用
福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全
安装swagger
//安装composer require darkaonline/l5-swaggerlaravel >= 5.5
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"php artisan l5-swagger:generate
laravel < 5.5
php artisan l5-swagger:publishphp artisan l5-swagger:publish-configphp artisan l5-swagger:publish-assetsphp artisan l5-swagger:publish-viewsphp artisan l5-swagger:generate
注意：在运行 php artisan l5-swagger:generate 命令之前，请确保在app目录下存在@OA\Info注解和 且至少定义一个@OA\Get 注解（接口） 否则会异常:
//这是基本信息/*** @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接口
/*** @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")* )* )*///UserModel定义/*** @OA\Schema(* schema="UserModel",* required={"username", "age"},* @OA\Property(* property="username",* type="string",* description="用户名称"* ),* @OA\Property(* property="age",* type="int",* description="年龄"* )* )*/
全局鉴权：注解
/*** @OA\SecurityScheme(* type="oauth2",* description="这里有多中校验方式：basic|apiKey|oauth2",* name="Password Based",* in="header|query",* scheme="https",* securityScheme="Password Based",* @OA\Flow(* flow="password",* authorizationUrl="/oauth/authorize",* tokenUrl="/oauth/token",* refreshUrl="/oauth/token/refresh",* scopes={}* )* )*/全局鉴权：config配置全局开启（l5-swagger.php）
'securityDefinitions' => ['securitySchemes' => [/** Examples of Security schemes*/'Authorization-Bearer' => [ // Unique name of security'type' => 'apiKey',// The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".'description' => '用户登录鉴权Token','name' => 'authorization',// 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".],]]
鉴权参数
| 参数 | 含义 |
|---|---|
| type | 类型 “http”, “apiKey”, “oauth2”, “openIdConnect” |
| name | 名称 |
| in | 需要API密钥的位置 值为 query、header |
| flow | OAuth2安全方案使用的流 值为：“implicit”、“password”、“application”或“accesscode” |
| authorizationUrl | OAuth2授权URL |
| scopes | OAuth2安全方案的可用范围 |
问题
如果在使用中遇到了Authorize：apiKey header模式情况下，token未通过header进行请求传递的话请参照修复
修改：/resource/views/vendor/l5-swagger/index.blade.php,主动添加token到头部
window.ui = uiui.getConfigs().requestInterceptor = function (request) {if (ui.authSelectors.authorized().size){var authObject = ui.authSelectors.authorized()._root.entries[0];var securityConfig = authObject[1]._root.entries[1][1]._list._tail.array;if (securityConfig[0][1] === 'apiKey' && securityConfig[3][1] === 'header') {var token = authObject[1]._root.entries[2][1];if (authObject[0] === 'Bearer' && !token.startsWith('Bearer ')){token = 'Bearer ' + token;}request.headers[securityConfig[2][1]] = token;}}request.headers['X-CSRF-TOKEN'] = '{{ csrf_token() }}';return request;}
演示
运行完php artisan l5-swagger:generate 命令后就可以通过浏览器查看接口文档(访问/api/documentation: 当然这个地址可以在l5-swagger.php配置文件中进行修改)
福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全