Laravel swagger接口文档生成和管理

Laravel swagger接口文档生成和管理

接口开发随着时间推移接口会越来越多，随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性越来越差, 需要一个工具来管理这些接口的文档, 并能够充当mock server给调用方使用

这里推荐swagger生成和管理接口文档，下面介绍基于laravel项目的swagger使用

福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全

安装swagger

    //安装composer require darkaonline/l5-swagger

laravel >= 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".],]]

鉴权参数

问题

如果在使用中遇到了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 大全