PHPackages                             madong/swagger - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. madong/swagger

ActiveLibrary[API Development](/categories/api)

madong/swagger
==============

Madong Swagger Documentation Module - 基于 webman-tech/swagger 的 Swagger 文档生成模块

2.0.6(1mo ago)0140Apache-2.0PHPPHP >=8.1

Since Mar 12Pushed 1mo agoCompare

[ Source](https://github.com/madong-code/swagger)[ Packagist](https://packagist.org/packages/madong/swagger)[ RSS](/packages/madong-swagger/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (5)Used By (0)

Madong Swagger 模块
=================

[](#madong-swagger-模块)

[![PHP >= 8.1](https://camo.githubusercontent.com/fabeba9a1fce5ab2d034002842f688c3a48beacc3845d75e287216c7c38e37e2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e312d383839324246)](https://www.php.net/releases/8.1/en.php)[![OpenAPI 3.0](https://camo.githubusercontent.com/3053fac48e3d67f52255e729ba5cd6aa459cf9160988756ad4708aa2e18297c3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4f70656e4150492d332e302d677265656e)](https://swagger.io/specification/)[![Webman](https://camo.githubusercontent.com/e988a3ffa5a16b585c67356e7a50119fb32cf10e8561242c920894913d9bc971/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5765626d616e2d253545322e302d626c7565)](https://www.workerman.net/webman)

一个功能强大、结构清晰的 Swagger/OpenAPI 文档生成模块，专为 Webman 框架设计。

📋 目录
----

[](#-目录)

- [功能特性](#%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7)
- [目录结构](#%E7%9B%AE%E5%BD%95%E7%BB%93%E6%9E%84)
- [快速开始](#%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
- [注解分类](#%E6%B3%A8%E8%A7%A3%E5%88%86%E7%B1%BB)
- [详细使用指南](#%E8%AF%A6%E7%BB%86%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97)
- [AnnotationHelper 使用](#annotationhelper-%E4%BD%BF%E7%94%A8)
- [IS\_REPEATABLE 支持](#is_repeatable-%E6%94%AF%E6%8C%81)
- [最佳实践](#%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5)
- [向后兼容](#%E5%90%91%E5%90%8E%E5%85%BC%E5%AE%B9)
- [常见问题](#%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98)
- [更新日志](#%E6%9B%B4%E6%96%B0%E6%97%A5%E5%BF%97)

✨ 功能特性
------

[](#-功能特性)

- **完整的 OpenAPI 3.0 支持**：基于 `zircote/swagger-php` 和 `webman-tech/swagger`
- **清晰的注解分类**：认证、操作、响应三类注解，职责分明
- **强大的响应注解**：支持 6 种响应类型（Data、Page、List、Tree、Result、Simple）
- **权限注解集成**：内置 AllowAnonymous 和 Permission 注解，支持权限中间件
- **AnnotationHelper 工具**：便捷获取控制器和方法的注解信息
- **IS\_REPEATABLE 支持**：响应注解支持在同一个方法上重复使用
- **向后兼容**：提供 `core\attribute` 别名类，兼容旧代码
- **灵活的示例数据**：支持多种数据格式（类、对象、JSON、数组）

📁 目录结构
------

[](#-目录结构)

```
packages/swagger/src/
├── attribute/              # 认证门面类（简化使用）
│   ├── AllowAnonymous.php       # 跳过认证注解
│   ├── Permission.php     # 权限注解
│   └── ValidationRule.php # 验证规则注解
│
├── annotation/            # 完整注解分类（实际实现）
│   ├── auth/              # 认证注解
│   │   ├── AllowAnonymous.php
│   │   ├── Permission.php
│   │   └── ValidationRule.php
│   │
│   ├── operation/         # 操作注解
│   │   ├── ApiOperation.php
│   │   ├── ApiParameter.php
│   │   └── ApiRequestBody.php
│   │
│   └── response/          # 响应注解（支持 IS_REPEATABLE）
│       ├── AbstractResponse.php
│       ├── DataResponse.php
│       ├── PageResponse.php
│       ├── ListResponse.php
│       ├── TreeResponse.php
│       ├── ResultResponse.php
│       ├── SimpleResponse.php
│       └── ResponseSchema.php
│
├── schema/                # Schema 基类
│   └── SchemaBase.php
│
└── helper/                # 辅助工具类
    ├── AnnotationHelper.php    # 注解查询工具
    ├── ResponseHelper.php      # 响应注解创建工具
    ├── ExampleHelper.php       # 示例数据生成工具
    └── SchemaHelper.php        # Schema 辅助工具

```

### 命名空间规范

[](#命名空间规范)

注解类型命名空间说明响应注解`madong\swagger\annotation\response\*`只在 annotation 中，支持 IS\_REPEATABLE认证注解`madong\swagger\attribute\*`推荐使用的门面类认证注解`madong\swagger\annotation\auth\*`实际实现（可用但不推荐）操作注解`madong\swagger\annotation\operation\*`只在 annotation 中Schema 注解`madong\swagger\annotation\schema\*`只在 annotation 中**重要**：响应类（DataResponse、PageResponse 等）只在 `annotation/response` 中存在，没有对应的 `attribute` 版本。认证类则同时存在于 `attribute` 和 `annotation/auth` 中。

🚀 快速开始
------

[](#-快速开始)

### 1. 安装

[](#1-安装)

```
cd server/packages/swagger
composer install
```

### 2. 配置路由

[](#2-配置路由)

在 `app/adminapi/config/route.php` 中注册 Swagger：

```
use Webman\Route;
use WebmanTech\Swagger\Swagger;
use OpenApi\Annotations as OA;

Route::group('/adminapi', function () {
    // Swagger 文档路由配置
    Swagger::create()->registerRoute([
        'route_prefix'   => '/openapi',
        'register_route' => true,
        'openapi_doc'    => [
            'scan_path' => [
                base_path('app/adminapi'),
                base_path('app/schema'),  // Schema 目录
            ],
            'exclude'   => [
                // 排除不需要扫描的文件
            ],
            'modify'    => function (OA\OpenApi $openapi) {
                $openapi->info->title   = config('app.name') . ' API';
                $openapi->info->version = '1.0.0';
                $openapi->servers       = [
                    new OA\Server([
                        'url'         => '/adminapi',
                        'description' => request()->host(),
                    ]),
                ];

                // 配置安全认证
                if (!$openapi->components instanceof OA\Components) {
                    $openapi->components = new OA\Components([]);
                }
                $openapi->components->securitySchemes = [
                    new OA\SecurityScheme([
                        'securityScheme' => 'api_key',
                        'type'           => 'apiKey',
                        'name'           => config('madong.jwt.app.token_name', 'Authorization'),
                        'in'             => 'header',
                    ]),
                ];
            },
        ],
    ]);
});
```

### 3. 创建 Schema

[](#3-创建-schema)

```