Laravel swagger接口文档生成和管理 - sdk社区

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

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

安装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:publish
    php artisan l5-swagger:publish-config
    php artisan l5-swagger:publish-assets
    php artisan l5-swagger:publish-views
    
    php 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 = ui

  ui.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配置文件中进行修改)