在 Laravel Swagger 中集成认证支持

最新推荐文章于 2025-07-27 20:42:26 发布
原创 最新推荐文章于 2025-07-27 20:42:26 发布 · 580 阅读 · 4 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#laravel #php

在 Laravel Swagger 中集成认证支持

在 Swagger/OpenAPI 中添加认证支持对于文档非常重要，它允许用户直接在文档界面测试需要认证的端点。以下是完整的集成方案：

完整解决方案

1. 定义安全方案

在你的控制器文件顶部添加安全方案定义：

/**
 * @OA\OpenApi(
 *     security={{"bearerAuth":{}}}
 * )
 * 
 * @OA\SecurityScheme(
 *     securityScheme="bearerAuth",
 *     type="http",
 *     scheme="bearer",
 *     bearerFormat="JWT"
 * )
 * 
 * @OA\SecurityScheme(
 *     securityScheme="apiKey",
 *     type="apiKey",
 *     in="header",
 *     name="X-API-Key"
 * )
 */
class ApiController extends Controller
{
    // 控制器代码...
}

2. 在端点中添加安全要求

在需要认证的端点中添加安全要求：

/**
 * @OA\Get(
 *     path="/api/user/profile",
 *     tags={"User"},
 *     summary="获取用户个人信息",
 *     security={{"bearerAuth":{}}},
 *     @OA\Response(
 *         response=200,
 *         description="成功响应",
 *         @OA\JsonContent(ref="#/components/schemas/User")
 *     ),
 *     @OA\Response(
 *         response=401,
 *         description="未认证",
 *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
 *     )
 * )
 */
public function getUserProfile()
{
    // 控制器代码...
}

3. 定义认证响应模型

添加认证相关的响应模型：

/**
 * @OA\Schema(
 *     schema="LoginRequest",
 *     required={"email", "password"},
 *     @OA\Property(property="email", type="string", format="email", example="user@example.com"),
 *     @OA\Property(property="password", type="string", example="password123")
 * )
 * 
 * @OA\Schema(
 *     schema="LoginResponse",
 *     @OA\Property(property="access_token", type="string", example="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."),
 *     @OA\Property(property="token_type", type="string", example="Bearer"),
 *     @OA\Property(property="expires_in", type="integer", example=3600)
 * )
 * 
 * @OA\Schema(
 *     schema="ErrorResponse",
 *     @OA\Property(property="error", type="string", example="Unauthorized"),
 *     @OA\Property(property="message", type="string", example="Authentication failed"),
 *     @OA\Property(property="code", type="integer", example=401)
 * )
 */

4. 创建认证端点文档

为登录端点添加文档：

/**
 * @OA\Post(
 *     path="/api/auth/login",
 *     tags={"Authentication"},
 *     summary="用户登录",
 *     description="通过邮箱和密码获取访问令牌",
 *     operationId="authLogin",
 *     security={},
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/LoginRequest")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="登录成功",
 *         @OA\JsonContent(ref="#/components/schemas/LoginResponse")
 *     ),
 *     @OA\Response(
 *         response=401,
 *         description="认证失败",
 *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
 *     )
 * )
 */
public function login(Request $request)
{
    // 登录逻辑...
}

5. 添加刷新令牌端点文档

/**
 * @OA\Post(
 *     path="/api/auth/refresh",
 *     tags={"Authentication"},
 *     summary="刷新访问令牌",
 *     description="使用刷新令牌获取新的访问令牌",
 *     operationId="authRefresh",
 *     security={},
 *     @OA\Response(
 *         response=200,
 *         description="令牌刷新成功",
 *         @OA\JsonContent(ref="#/components/schemas/LoginResponse")
 *     ),
 *     @OA\Response(
 *         response=401,
 *         description="无效的刷新令牌",
 *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
 *     )
 * )
 */
public function refresh()
{
    // 刷新令牌逻辑...
}

6. 添加登出端点文档

/**
 * @OA\Post(
 *     path="/api/auth/logout",
 *     tags={"Authentication"},
 *     summary="用户登出",
 *     description="使当前访问令牌失效",
 *     operationId="authLogout",
 *     security={{"bearerAuth":{}}},
 *     @OA\Response(
 *         response=200,
 *         description="登出成功",
 *         @OA\JsonContent(
 *             @OA\Property(property="message", type="string", example="Successfully logged out")
 *         )
 *     ),
 *     @OA\Response(
 *         response=401,
 *         description="未认证",
 *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
 *     )
 * )
 */
public function logout()
{
    // 登出逻辑...
}

7. 全局认证设置 (config/l5-swagger.php)

在配置文件中添加全局认证设置：

return [
    // ...
    
    'swagger_security' => [
        'bearerAuth' => [
            'type' => 'http',
            'scheme' => 'bearer',
            'bearerFormat' => 'JWT',
        ],
        'apiKey' => [
            'type' => 'apiKey',
            'name' => 'X-API-Key',
            'in' => 'header',
        ],
    ],
    
    'security' => [
        [
            'bearerAuth' => [],
        ],
    ],
];

使用说明

  1. 在 Swagger UI 中，点击右上角的 Authorize 按钮
  2. 对于 Bearer 认证：
    • 输入访问令牌（不包括 “Bearer” 前缀）
    • 点击 Authorize
  3. 对于 API Key 认证：
    • 在值字段中输入您的 API 密钥
    • 点击 Authorize

高级技巧

1. 权限控制文档

/**
 * @OA\Get(
 *     path="/api/admin/users",
 *     tags={"Admin"},
 *     summary="获取所有用户 (仅管理员)",
 *     security={
 *         {"bearerAuth":{}},
 *         {"apiKey":{}}
 *     },
 *     @OA\Response(
 *         response=200,
 *         description="成功响应",
 *         @OA\JsonContent(type="array", @OA\Items(ref="#/components/schemas/User"))
 *     ),
 *     @OA\Response(
 *         response=403,
 *         description="禁止访问",
 *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
 *     )
 * )
 */
public function getAllUsers()
{
    // 需要管理员权限...
}

2. OAuth2 支持

/**
 * @OA\SecurityScheme(
 *     securityScheme="oauth2",
 *     type="oauth2",
 *     @OA\Flow(
 *         authorizationUrl="/oauth/authorize",
 *         tokenUrl="/oauth/token",
 *         flow="authorizationCode",
 *         scopes={
 *             "read": "读取权限",
 *             "write": "写入权限",
 *             "admin": "管理员权限"
 *         }
 *     )
 * )
 */

3. 刷新令牌控制器示例

public function refresh()
{
    try {
        $newToken = auth()->refresh();
    
        return response()->json([
            'access_token' => $newToken,
            'token_type' => 'bearer',
            'expires_in' => auth()->factory()->getTTL() * 60
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'error' => 'token_expired',
            'message' => '刷新令牌已过期',
            'code' => 401
        ], 401);
    }
}

最佳实践

  1. 统一认证响应格式：确保所有认证错误返回相同的结构
  2. 文档版本控制：添加认证方式到API版本信息中
  3. 范围标注：对OAuth2认证添加权限范围说明
  4. 测试账号：在文档描述中添加测试用的账号信息
  5. 令牌生命周期：在文档中说明令牌的有效期和刷新机制
  6. 安全建议：添加关于安全存储令牌的说明

通过以上配置，Swagger文档将支持完整的认证流程，可以直接在文档界面进行认证并测试受保护的API端点。

后端——》JWT结合swagger进行接口安全认证
叙传
10-18 1437
JWT（json web token）。 1，jwt(全称json web token)。主要是用来生成token的，token是一串加密过的字符串。 流程是这样的 用户使用用户名密码请求服务器 服务器进行验证用户信息，并生成一个token存在数据库中 服务器通过验证并把token发送给用户 客户端存储token，一般存在local Storage。并在每次请求时附加这个t...
laravel整合Swagger
m0_46361249的博客
11-09 338
一,安装 1.删除composer.lock 2.在composer.json文件里面的require 添加包 "darkaonline/l5-swagger": "^6.2", 3.清楚缓存 composer clearcache 4.更新依赖（重新生成 composer.lock） composer update 5.安装完成后，使用如下 Artisan 命令发布该扩展包的配置和视图文件： php artisan vendor:publish --provider "L5Swagger\L5Sw
Springdoc Swagger UI集成OAuth2认证
罗小爬的技术宝书
02-26 3445
本文主要介绍了Springdoc Swagger UI集成OAuth2认证的3种方式：Bearer Token、标准OAuth2授权码流程、集成OIDC发现端点。
Swagger 线上文档授权的几种方式
weixin_38045727的博客
06-07 5305
Swagger方便开发和联调，同时也会存在接口安全问题。所以在生产环境是禁止开放Swagger的，或者更严格一点，SIT、UAT都必须授权访问，Swagger安全方式通常有几种：在Swagger接口中添加认证授权机制，例如JWT令牌和OAuth2.0认证。使用Spring Security框架进行安全管理，针对Swagger接口添加相应的权限配置和拦截器。进行IP访问控制，只允许特定的IP地址访问Swagger接口。对Swagger接口进行加密，例如使用SSL证书或TLS协议进行数据加密传输。
swagger接口需要权限验证解决方案
ybb_ymm的专栏
03-15 1万+
背景：当我们在使用swagger的情况下，经常会遇到需要授权或者请求带有token才可以访问接口，这里我们就是解决授权问题。 废话不多说，我们直接给出解决方案，具体代码如下： import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuild
Swagger详细解释
2302_76649176的博客
11-28 800
去扫描controller的类,控制层有swagger需要的请求路径、请求方式、请求参数、响应内容。创建学生类控制层,在类和方法上写上对应的信息,会自动显示到swagger文档里。如果有配置Security,会对swagger进行拦截,需要对它进行配置。该注解是写在方法上,给方法做简单表示,解释默认给value赋值。notes是该方法的一些注意点,多个注解value不可省略。这个注解是写在控制层上方,给该控制层做简单表示。导入这个依赖时,之前导入的那两个依赖可以删掉。他们之间有联系,会一起导入之前的依赖。
Laravel Swagger 使用完整教程
09-20
在 Laravel 框架中，我们可以方便地集成 Swagger 来增强项目开发的效率和用户体验。 ### 一、什么是 Swagger Swagger 是一种 RESTful API 的描述语言，它基于 OpenAPI 规范，允许开发者以 YAML 或 JSON 格式定义 ...
Laravel与Swagger集成：打造用户界面新体验
### Laravel开发中的Laravel-Swagger集成 #### 标题知识解析 “Laravel开发-laravel-swagger”这个标题直接指向了在Laravel项目中集成了Swagger的开发实践。Laravel是一个流行的PHP Web应用框架，以其优雅的语法和...
Laravel开发中的Swagger Lite集成与应用
2. 阅读相关文档说明，了解如何在Laravel项目中集成Swagger lite。 3. 在Laravel项目的适当位置引入Swagger配置文件，例如在`routes/api.php`中注册Swagger路由。 4. 根据需要配置Swagger的设置，如API版本、API描述...
Laravel Swagger API包：提升RESTful API开发效率
- 如何在Laravel项目中安装laravel-swagger-api包。 - 扩展包对Laravel路由和控制器的集成方式。 - 如何配置laravel-swagger-api以适应不同的API设计需求。 - 如何通过laravel-swagger-api自动生成API文档。 - ...
java api安全验证_swagger添加权限验证保证API（接口）安全性(两种方法)
weixin_36317492的博客
02-23 1429
当我们使用swagger，进行接口测试，怕接口不安全，担心暴露。可采用两种方式1.环境权限配置对swagger文档配置只在测试环境可访问，生产环境不可访问。@Profile({"dev","test"})如以上配置，则只有在dev以及test环境有效，在生产环境不可访问。2.账户权限配置在1.9.0版本时,针对Swagger的资源接口,SwaggerBootstrapUi提供了简单的Basic认证...
Swagger如何访问需要权限验证的Web API
热门推荐
li123128的博客
07-02 3万+
Swagger如何访问需要权限验证的Web API这篇博文不是对asp.net core中使用Swagger作介绍，因为社区博客作了详细说明。今天主要说一下Swagger在Ocelot网关权限验证模式下的访问，以及Swagger请求应答的数据格式。首先创建四个项目：SwaggerOcelot：asp.net core web api类型，api网关项目SwaggerAuthorize：asp.ne...
swagger2-ui是怎么添加认证的
jupiter_888的博客
08-27 1198
https://www.jianshu.com/p/7a24d202b395 因为的是swagger2-ui所以在swagger2内维护了一个cookie和session, 但是在spring-security却没有这样session维护， 所以swagger2-ui登录一次就行了， spring-security依然是stateless的，不会维护session的。 swagge...
解决swagger接口每次都要输入JWT Authorization认证的问题
master_JP的博客
10-27 8410
解决swagger接口每次都要输入Authorization验证问题 配置示例： package cn.fc.swagger2; import com.google.common.base.Function; import com.google.common.base.Optional; import com.google.common.base.Predicate; import com.g...
SpringBoot添加swagger2接口并添加全局Authorization参数
景月娇-Kathy
10-08 8141
需求： 在项目实践中，我们需要Token值去向后端发送请求，后端根据Token值去判断用户，根据不同的用户返回对应的信息。这就是Token验证。 Token是在客户端频繁向服务端请求数据，服务端频繁的去数据库查询用户名和密码并进行对比，判断用户名和密码正确与否，并作出相应提示，在这样的背景下，Token便应运而生。Token是服务端生成的一串字符串，以作客户端进行请求的一个令牌，当第一次登录...
Swagger生成的接口需要权限验证的处理方法
weixin_33778544的博客
01-25 5177
通常开发API的时候需要对接口进行权限验证，而我们在使用Swagger生成接口文档界面的时候，直接调用需要权限验证的接口会提示"当前用户没有登陆" 为了解决此问题，我们需要更改一下Swagger的配置， 找到Startup文件，我们看到Swagger的配置如下： services.AddSwaggerGen(options => { ...
Red靶机攻略
最新发布
duanjiaxu6666的博客
07-27 1407
使用php伪协议访问:http://redrocks.win/NetworkFileManagerPHP.php?建立pass.txt文件,将之前配置文件那个密码放入,然后利用hashcat对应的base64规则去枚举相关的密码,存入passlist.txt中,格式是类似于之前获得的那个密码的,最好利用hydra进行爆破,获得对应的密码。
Android-广播详解
2401_87366139的博客
07-26 988
分类：标准广播是一个完全异步执行的广播，几乎同时的接收器会收到这个广播，效率比较高，无法截断；有序广播是同步执行，同一时刻只有一个接受器才能接受到消息，优先级高的接收器先接受到，同时也可以进行截断。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值