{"id":30178416,"url":"https://github.com/webman-tech/swagger","last_synced_at":"2026-03-11T10:32:09.884Z","repository":{"id":181800314,"uuid":"637452631","full_name":"webman-tech/swagger","owner":"webman-tech","description":"[READ ONLY] Subtree split from webman-tech/components-monorepo","archived":false,"fork":false,"pushed_at":"2026-03-04T03:13:26.000Z","size":226,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-05T01:34:02.699Z","etag":null,"topics":["openapi","swagger","webman"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webman-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-07T15:47:26.000Z","updated_at":"2026-03-04T03:13:30.000Z","dependencies_parsed_at":"2024-04-28T15:27:32.228Z","dependency_job_id":"7cacb7d7-5534-48bb-8d73-ac25aa221d56","html_url":"https://github.com/webman-tech/swagger","commit_stats":null,"previous_names":["webman-tech/swagger"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/webman-tech/swagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webman-tech%2Fswagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webman-tech%2Fswagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webman-tech%2Fswagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webman-tech%2Fswagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webman-tech","download_url":"https://codeload.github.com/webman-tech/swagger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webman-tech%2Fswagger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30378081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi","swagger","webman"],"created_at":"2025-08-12T05:20:50.644Z","updated_at":"2026-03-11T10:32:09.867Z","avatar_url":"https://github.com/webman-tech.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# webman-tech/swagger\n\n本项目是从 [webman-tech/components-monorepo](https://github.com/orgs/webman-tech/components-monorepo) 自动 split\n出来的，请勿直接修改\n\n\u003e 简介\n\n[swagger openapi](https://swagger.io/) 在 webman 中一键配置启用\n\n## 安装\n\n```bash\ncomposer require webman-tech/swagger\n```\n\n## 特点\n\n- 基于 [zircote/swagger-php](https://github.com/zircote/swagger-php)（支持 Attribute 模式）\n- 支持零配置启动（安装后直接访问 /openapi 即可看到 swagger UI 的界面）\n- 支持单应用下多个 swagger 文档（多路由，不同 api 文档）\n- 支持动态修改注解下的 swagger 文档（解决注解下无法写动态配置的问题）\n- 支持丰富的配置（host 访问限制 / swagger-ui 配置 / openapi 配置）\n- 性能优先（服务启动后缓存，开发环境支持自动更新）\n- 支持自动注册 webman 路由（已经写了 openapi 文档，再写一遍 webman Route 是不是多此一举？）\n- 不仅仅支持 webman 环境（非一键启动，需要调整配置）\n\n## 使用\n\n### 零配置\n\n安装完依赖后打开 `/openapi` 即可访问 swagger 文档\n\n默认扫描整个 `app_path()`\n\n### 修改 @OA\\Info 等全局的配置\n\n第一种：通过添加注释的方式修改\n\n```php\n\u003c?php\n\nnamespace app\\swagger;\n\nuse OpenApi\\Attributes as OA;\n\n/**\n * @link https://swagger.io/specification/#info-object\n */\n#[OA\\Info(version: '1.0.0', title: 'My App')]\n#[OA\\Server(url: '/api', description: 'localhost')]\nclass OpenapiSpec\n{\n}\n```\n\n第二种：通过 modify 的方式修改（建议：因为这种方式支持更加复杂和动态的配置）\n\n以下 `openapi_doc` 支持配置在 全局 和 应用级别（见 [配置说明](#配置说明)）\n\n```php\nuse OpenApi\\Annotations as OA;\n\n'openapi_doc' =\u003e [\n    'modify' =\u003e function(OA\\OpenApi $openApi) {\n        $openApi-\u003einfo-\u003etitle = 'My App';\n        $openApi-\u003einfo-\u003eversion = '1.0.0';\n        \n        $openApi-\u003eservers = [\n            new OA\\Server(['url' =\u003e '/api', 'description' =\u003e 'localhost']),\n        ];\n    }\n]\n```\n\n### 限制访问\n\n为了保证接口文档的安全性，不应该让接口暴露在公网环境下\n\n默认 `host_forbidden` 开启，仅内网环境下可访问，见 [HostForbiddenMiddleware](src/Middleware/HostForbiddenMiddleware.php)\n\n可以通过配置 `app.php` 中的 `host_forbidden` `enable =\u003e false` 来全局关闭\n\n### 多应用支持\n\n默认通过配置 `app.php` 中的 `global_route` 配置会启用全局的扫描 `app_path()` 的文档，\n可以通过设置 `enable =\u003e false` 来关闭\n\n在需要的地方通过 `Swagger::create()-\u003eregisterRoute()` 来手动注册文档路由\n\n如：\n\n```php\n\u003c?php\n\nuse Webman\\Route;\nuse WebmanTech\\Swagger\\Swagger;\n\nRoute::group('/api1', function () {\n    Swagger::create()-\u003eregisterRoute([\n        'route_prefix' =\u003e '/openapi',\n        'openapi_doc' =\u003e [\n            'scan_path' =\u003e app_path() . '/controller/api1',\n        ],\n    ]);\n\n    Route::get('/test', [\\app\\controller\\Test::class, 'index']);\n});\n\nRoute::group('/api2', function () {\n    Swagger::create()-\u003eregisterRoute([\n        'route_prefix' =\u003e '/my-doc',\n        'openapi_doc' =\u003e [\n            'scan_path' =\u003e app_path() . '/controller/api2',\n        ],\n    ]);\n\n    Route::get('/test', [\\app\\controller\\Test::class, 'index']);\n});\n```\n\n如此配置，支持通过 `/api1/openapi` 访问 `api1` 的文档，`/api2/my-doc` 访问 `api2` 的文档\n\n## 配置说明\n\n很多配置都支持全局（多应用共享）、应用级别（仅当前应用生效）\n\n`app.php` 中的配置是全局的\n\n`Swagger::create()-\u003eregisterRoute($config)` 中的传参 `$config` 是应用级别的\n\n## webman 路由自动注册\n\n在 config 的 `app.php` 中修改 `register_route` 为 true 即可自动注册 webman 路由\n\n## 路由传参与 swagger 文档绑定，并且支持自动校验（仅支持 php\u003e=8.1）\n\n建立一个 Form（可同时用于 POST 和 GET，可以无需任何的 Swagger 注解，也能用）\n\n```php\n\u003c?php\n\nnamespace app\\form;\n\nuse WebmanTech\\DTO\\Attributes\\ValidationRules;\nuse WebmanTech\\DTO\\BaseRequestDTO;\nuse WebmanTech\\DTO\\BaseResponseDTO;\n\nclass TestForm extends BaseRequestDTO {\n    /**\n     * 名称\n     * @example webman\n     */\n    public string $name = '';\n    /**\n     * 年龄\n     * @example 5 \n     */\n    #[ValidationRules(max: 100)]\n    public int $age = 0;\n    /**\n     * 备注\n     */\n    public string $remark = '';\n    \n    public function doSomething(): TestFormResult {\n        return new TestFormResult(\n            name: 'abc',\n        )\n    }\n}\n\nclass TestFormResult extends BaseResponseDTO {\n    public function __construct(\n        /**\n         * 名称\n         */\n        public string $name,\n    ) {\n    }\n}\n```\n\n控制器\n\n```php\n\nuse app\\form\\TestForm;\nuse OpenApi\\Attributes as OA;\nuse WebmanTech\\Swagger\\DTO\\SchemaConstants;\n\nclass IndexController {\n     #[OA\\Post(\n        path: '/xxx',\n        summary: '接口说明',\n        x: [\n            SchemaConstants::X_SCHEMA_REQUEST =\u003e TestForm::class . '@doSomething'\n        ],\n    )]\n    public function md(Request $request) {\n        return TestForm::fromRequest($request)\n            -\u003edoSomething()\n            -\u003etoResponse();\n    }\n    \n    #[OA\\Get(\n        path: '/xxx',\n        summary: '接口说明',\n        x: [\n            SchemaConstants::X_SCHEMA_REQUEST =\u003e TestForm::class . '@doSomething'\n        ],\n    )]\n    public function md(Request $request) {\n        return TestForm::fromRequest($request)\n            -\u003edoSomething()\n            -\u003etoResponse();\n    }\n}\n```\n\n## 参考\n\n[webman 使用最佳实践](https://github.com/krissss/webman-basic/tree/master/app/api)\n\n[webman 使用 swagger 示例：注解模式的 crud](https://github.com/webman-tech/webman-samples/tree/swagger-attributions)\n\n[webman 使用 swagger 示例：多 swagger 文档](https://github.com/webman-tech/webman-samples/tree/swagger-multi)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebman-tech%2Fswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebman-tech%2Fswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebman-tech%2Fswagger/lists"}