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.22(2mo ago)72.5k21MITPHPPHP ^8.2

Since Jan 10Pushed 3w 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 3w ago

READMEChangelog (10)Dependencies (9)Versions (71)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
```

核心组件
----

[](#核心组件)

### Swagger 主类

[](#swagger-主类)

[Swagger](src/Swagger.php) 是主要入口，提供 `registerGlobalRoute()` 注册全局路由和 `registerRoute()` 注册自定义路由两个方法。

### 配置 DTO

[](#配置-dto)

#### ConfigRegisterRouteDTO

[](#configregisterroutedto)

路由注册配置，控制路由注册行为，包含启用开关（`enable`）、路由前缀（`route_prefix`）、访问权限控制（`host_forbidden`）、Basic 认证（`basic_auth`）、Swagger UI 配置（`swagger_ui`）、OpenAPI 文档配置（`openapi_doc`）、是否注册 webman 路由（`register_route`）及额外中间件（`middlewares`）。

#### ConfigBasicAuthDTO

[](#configbasicauthdto)

Basic 认证配置，默认关闭。启用后访问 Swagger UI 和 OpenAPI 文档时需要提供用户名和密码。支持配置用户名（`username`）、密码（`password`）和认证提示域（`realm`）。

#### ConfigOpenapiDocDTO

[](#configopenapidocdto)

OpenAPI 文档配置，默认输出版本为 OpenAPI 3.1.0，支持扫描目录（`scan_path`）、排除目录（`scan_exclude`）、文档格式（`format`，yaml/json）、运行时动态修改回调（`modify`）、缓存键（`cache_key`）及 Schema 相关配置。

#### ConfigSwaggerUiDTO

[](#configswaggeruidto)

Swagger UI 配置，支持自定义视图（`view`）、视图路径（`view_path`）、静态资源基础 URL（`assets_base_url`）及视图数据（`data`）。

#### ConfigHostForbiddenDTO

[](#confighostforbiddendto)

主机访问限制配置，支持启用开关（`enable`）、允许内网访问（`ip_white_list_intranet`）、IP 白名单（`ip_white_list`）及主机白名单（`host_white_list`）。默认仅允许内网环境访问。

### OpenapiController

[](#openapicontroller)

[OpenapiController](src/Controller/OpenapiController.php) 负责处理文档展示，提供 `swaggerUI()` 展示 Swagger UI 界面和 `openapiDoc()` 返回 OpenAPI 文档内容两个动作。

### Reader 路由注解解析

[](#reader-路由注解解析)

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

### SchemaConstants 常量定义

[](#schemaconstants-常量定义)

[SchemaConstants](src/DTO/SchemaConstants.php) 定义了用于 Schema 的扩展常量，包括 `X_NAME`（命名路由）、`X_PATH`（路由路径）、`X_MIDDLEWARE`（路由中间件）、`X_SCHEMA_REQUEST`（请求 Schema）、`X_SCHEMA_RESPONSE`（响应 Schema）。

参考示例
----

[](#参考示例)

- [webman 使用最佳实践](https://github.com/krissss/webman-basic/tree/master/app/api)
- [webman 使用 swagger 示例：注解模式的 crud](https://github.com/webman-tech/webman-samples/tree/swagger-attributions)
- [webman 使用 swagger 示例：多 swagger 文档](https://github.com/webman-tech/webman-samples/tree/swagger-multi)

AI 辅助
-----

[](#ai-辅助)

- **开发维护**：[AGENTS.md](AGENTS.md) — 面向 AI 的代码结构和开发规范说明
- **使用指南**：[skills/webman-tech-swagger-best-practices/SKILL.md](skills/webman-tech-swagger-best-practices/SKILL.md) — 面向 AI 的最佳实践，可安装到 Claude Code 的 skills 目录使用

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance92

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Total

67

Last Release

64d ago

Major Versions

v1.0.5 → v2.1.12025-07-31

v1.0.7 → v2.1.22025-09-08

v1.0.18 → v2.1.32025-10-18

v1.0.25 → v2.1.42025-11-13

v2.1.4 → v5.0.02025-11-24

PHP version history (2 changes)v1.1.0PHP >=7.2

v1.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/b4053cfc9956b8c15b9bc4c9c7c2bad625d16d1b6d9191019b2a25cc0972d955?d=identicon)[kriss](/maintainers/kriss)

---

Top Contributors

[![krissss](https://avatars.githubusercontent.com/u/10680903?v=4)](https://github.com/krissss "krissss (104 commits)")

---

Tags

openapiswaggerwebman

### Embed Badge

![Health badge](/badges/webman-tech-swagger/health.svg)

```
[![Health](https://phpackages.com/badges/webman-tech-swagger/health.svg)](https://phpackages.com/packages/webman-tech-swagger)
```

###  Alternatives

[darkaonline/l5-swagger

OpenApi or Swagger integration to Laravel

2.9k36.4M126](/packages/darkaonline-l5-swagger)[darkaonline/swagger-lume

OpenApi or Swagger integration to Lumen

3322.4M3](/packages/darkaonline-swagger-lume)[jlapp/swaggervel

A great way to integrate Swagger into Laravel

484944.2k2](/packages/jlapp-swaggervel)[light/yii2-swagger

swagger intergation with yii2

153835.2k4](/packages/light-yii2-swagger)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.4M517](/packages/shopware-core)[yii2mod/yii2-swagger

Swagger Documentation Generator for Yii2 Framework

63398.2k9](/packages/yii2mod-yii2-swagger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)