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

本贴最后更新于 2127 天前,其中的信息可能已经事过境迁

环境

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
得到结果如下:
imagepng

特别注意红框文件,这就是 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 文件夹下放入静态文件

imagepng
此处将 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/
imagepng

成果

imagepng

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

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

  • PHP

    PHP(Hypertext Preprocessor)是一种开源脚本语言。语法吸收了 C 语言、 Java 和 Perl 的特点,主要适用于 Web 开发领域,据说是世界上最好的编程语言。

    179 引用 • 407 回帖 • 488 关注
  • Swagger

    Swagger 是一款非常流行的 API 开发工具,它遵循 OpenAPI Specification(这是一种通用的、和编程语言无关的 API 描述规范)。Swagger 贯穿整个 API 生命周期,如 API 的设计、编写文档、测试和部署。

    26 引用 • 35 回帖 • 2 关注
  • Laravel

    Laravel 是一套简洁、优雅的 PHP Web 开发框架。它采用 MVC 设计,是一款崇尚开发效率的全栈框架。

    20 引用 • 23 回帖 • 721 关注

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • 2501224066

    swagger 写文档要写好多注释,累得很 😂