php laravel 框架使用 swagger 生成接口文档

环境

PHP 7.2

Laravel 5.6

安装

一、安装 swagger-php

项目根目录下运行命令：composer require zircote/swagger-php
静待命令执行完成即可

二、下载 swagger-ui

运行 git 指令：git clone https://github.com/swagger-api/swagger-ui.git
得到结果如下：

特别注意红框文件，这就是 swagger 静态界面

配置

一、配置一个接口提供数据

接口

	namespace App\Http\Controllers;
	use Illuminate\Http\Request;
	use Swagger\Annotations\Info;
	use Swagger\Annotations\OA;
	/**
	 * @OA\Info(title="My First API", version="0.1")
	 */
	​
	/**
	 * @OA\Get(
	 *     path="/api/resource.json",
	 *     @OA\Response(response="200", description="An example resource")
	 * )
	 */
	class SwaggerController extends Controller
	{
	   public function doc()
	   {
		 $swagger = \OpenApi\scan(app_path('Http/Controllers/Api'));
		 return response()->json($swagger);
	   }
	}
​

路由

	Route::get('/swagger/doc', 'SwaggerController@doc'); 
​

二、集成 swagger-ui

public 文件夹下放入静态文件

此处将 dist 目录改名后放入

配置数据获取接口, 打开 swagger-ui下 的 index.html,找到如下代码，更换 url 配置

	window.onload = function() {
		// Begin Swagger UI call region
		const  ui = SwaggerUIBundle({
		//url: "https://petstore.swagger.io/v2/swagger.json", //旧的配置
		url:  "/swagger/doc", //新的配置
		dom_id:  '#swagger-ui',
		deepLinking:  true,
		presets: [
		SwaggerUIBundle.presets.apis,
		SwaggerUIStandalonePreset
		],
		plugins: [
		SwaggerUIBundle.plugins.DownloadUrl
		],
		layout:  "StandaloneLayout"
		})
		// End Swagger UI call region
		window.ui = ui
	}
​

示例

PackageInfo.php

namespace App\Http\Controllers;
/**
 * @OA\Info(title="好像有货接口文档", version="0.1")
 */
class PackageInfo {
}
​

UserController.php

/**
 * @OA\Tag(
 *     name="user",
 *     description="用户模块",
 * )
 */
class UserController extends Controller
{

    /**
     * @OA\Post(
     *     path="/api/login",
     *     tags={"user"},
     *     summary="登录",
     *     @OA\Parameter(name="isFastLogin", in="query", @OA\Schema(type="boolean")),
     *     @OA\Parameter(name="tel", in="query", @OA\Schema(type="string")),
     *     @OA\Parameter(name="verification_code", in="query", @OA\Schema(type="string")),
     *     @OA\Parameter(name="password", in="query", @OA\Schema(type="string")),
     *     @OA\Response(response=200, description="  {err_code: int32, msg:string, data:[]}  "
     *     )
     * )
     */
    public function login(Request $request)
    {
    }
}
​

更多实例

项目根路径: /vendor/zircote/Examples/

成果

+++++++++++++++++++++++++++++++++++

YouY Blog —— 专心做你的烂笔头。访问主页