PHPackages                             webman-tech/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. webman-tech/swagger

ActiveLibrary[API Development](/categories/api)

webman-tech/swagger
===================

Webman plugin webman-tech/swagger

v5.0.19(1mo ago)72.3k↓100%21MITPHPPHP ^8.2

Since Jan 10Pushed 1mo ago1 watchersCompare

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

READMEChangelog (10)Dependencies (3)Versions (68)Used By (1)

webman-tech/swagger
===================

[](#webman-techswagger)

本项目是从 [webman-tech/components-monorepo](https://github.com/orgs/webman-tech/components-monorepo) 自动 split 出来的，请勿直接修改

简介
--

[](#简介)

[Swagger OpenAPI](https://swagger.io/) 在 webman 中的一键配置启用方案，基于 [zircote/swagger-php](https://github.com/zircote/swagger-php) 实现。

该组件提供了一种简便的方式来为 webman 应用生成和展示 API 文档，支持通过注解或属性(Attribute)方式定义 API 接口，并自动生成对应的 OpenAPI 文档和 Swagger UI 界面。

功能特性
----

[](#功能特性)

- **零配置启动**：安装后直接访问 `/openapi` 即可看到 Swagger UI 界面
- **多文档支持**：支持单应用下多个 Swagger 文档（多路由，不同 API 文档）
- **动态配置**：支持动态修改注解下的 Swagger 文档（解决注解下无法写动态配置的问题）
- **丰富配置**：支持 host 访问限制、Swagger UI 配置、OpenAPI 配置等
- **性能优化**：服务启动后缓存文档内容，开发环境支持自动更新
- **路由自动注册**：支持自动注册 webman 路由
- **跨框架兼容**：不仅仅支持 webman 环境，也可在其他环境中使用（需要调整配置）

安装
--

[](#安装)

```
composer require webman-tech/swagger
```

快速开始
----

[](#快速开始)

### 零配置使用

[](#零配置使用)

安装依赖后直接访问 `/openapi` 即可查看 Swagger 文档，默认会扫描整个 `app_path()` 目录。

### 基本配置

[](#基本配置)

在 `config/plugin/webman-tech/swagger/app.php` 中配置：

```
return [
    'global_route' => [
        'enable' => true,
        'route_prefix' => '/openapi',
        'openapi_doc' => [
            'scan_path' => [app_path()],
        ],
    ],
];
```

核心组件
----

[](#核心组件)

### Swagger 主类

[](#swagger-主类)

[Swagger](src/Swagger.php) 类是主要入口，用于注册路由和生成文档：

```
use WebmanTech\Swagger\Swagger;

// 注册全局路由
Swagger::create()->registerGlobalRoute();

// 注册自定义路由
Swagger::create()->registerRoute([
    'route_prefix' => '/api-doc',
    'openapi_doc' => [
        'scan_path' => [app_path() . '/controller/api'],
    ],
]);
```

### 配置 DTO

[](#配置-dto)

#### ConfigRegisterRouteDTO

[](#configregisterroutedto)

路由注册配置，用于控制路由注册行为：

- `enable`: 是否启用
- `route_prefix`: OpenAPI 文档的路由前缀
- `host_forbidden`: 访问权限控制配置
- `swagger_ui`: Swagger UI 配置
- `openapi_doc`: OpenAPI 文档配置
- `register_route`: 是否注册 webman 路由

#### ConfigOpenapiDocDTO

[](#configopenapidocdto)

OpenAPI 文档配置：

默认输出版本为 `OpenAPI 3.1.0`，可通过 `openapi_version` 配置项修改（如 `'3.0.0'`）。

- `scan_path`: 扫描的目录
- `scan_exclude`: 扫描忽略的目录
- `format`: 文档格式（yaml/json）
- `modify`: 修改 OpenAPI 对象的回调函数
- `cache_key`: 缓存用的 key
- `schema_*`: Schema 相关配置

#### ConfigSwaggerUiDTO

[](#configswaggeruidto)

Swagger UI 配置：

- `view`: 视图名称
- `view_path`: 视图路径
- `assets_base_url`: 静态资源基础 URL
- `data`: 视图数据

#### ConfigHostForbiddenDTO

[](#confighostforbiddendto)

主机访问限制配置：

- `enable`: 是否启用
- `ip_white_list_intranet`: 是否允许内网访问
- `ip_white_list`: 允许访问的指定 IP
- `host_white_list`: 允许访问的指定主机

### 控制器

[](#控制器)

[OpenapiController](src/Controller/OpenapiController.php) 负责处理文档展示和接口：

- `swaggerUI()`: 展示 Swagger UI 界面
- `openapiDoc()`: 返回 OpenAPI 文档内容

### 路由注解解析

[](#路由注解解析)

[Reader](src/RouteAnnotation/Reader.php) 类用于解析 OpenAPI 注解并生成路由配置：

```
use WebmanTech\Swagger\RouteAnnotation\Reader;

$reader = new Reader();
$routes = $reader->getData($scanSources);
```

使用指南
----

[](#使用指南)

### 修改全局配置

[](#修改全局配置)

#### 方法一：通过注解修改

[](#方法一通过注解修改)

```