源码系统概览
文章正文
Think OpenAPI 是一套面向 ThinkPHP 8 API 项目的轻量级 OpenAPI 3.1 生成器与文档 UI 组件源码。
项目由 c-v-c-v 开源维护，仓库获 2 个 star 关注，采用 MIT 协议发布，以 2026.9.22 源码打包为版本口径，README 最后更新 2026 年 9 月；组件体量轻小，注解类覆盖控制器、校验器与资源类三层结构，文档路由随包内置，接入后无需额外配置即可输出 OpenAPI 3.1 规范文件与在线页面。
源码简介
接口文档与代码脱节是常见痛点，组件用 PHP8 原生注解把文档写在控制器与校验器上，随代码一起演进。
复用项目既有的 Validate 校验器与 Resource 资源类，参数与响应结构自动映射进 OpenAPI 定义。
生成 OpenAPI 3.1 规范文件并内置文档 UI，前端与测试可直接在线查阅调试。
组件的使用方式是在控制器与校验器类上添加原生注解，README 示例展示 UserValidate 与 UserResource 的注解写法与文档路由的输出效果。
对比 swagger-php 和 Apidoc，区别在于 Think OpenAPI 的 ThinkPHP 8 原生注解与校验器复用。
| 对比维度 | Think OpenAPI | swagger-php 注解方案 |
|---|---|---|
| 框架适配 | ThinkPHP 8 原生 | 通用但需胶水 |
| 注解方式 | PHP8 原生注解 | DocBlock 注释解析 |
| 结构复用 | 校验器资源类直读 | 重复书写定义 |
| 输出规范 | OpenAPI 3.1 | 多为 2.0 或 3.0 |
ThinkPHP 8 项目想摆脱手工维护接口文档，接入组件后注解即文档。
适用场景
- ThinkPHP 8 项目接口文档自动生成
- 前后端协作的在线接口查阅与调试
- 基于 OpenAPI 规范的接口测试对接
技术栈与运行环境
组件以 composer 包形式发布，注解类覆盖控制器、校验器与资源类三层。
生成产物为 OpenAPI 3.1 规范，内置 UI 组件直接渲染文档页面。
功能亮点
- PHP8 原生注解驱动
- 校验器与资源类自动映射
- OpenAPI 3.1 规范输出
- 内置文档 UI 组件
- composer 一行接入
技术架构与部署指南
安装与部署提示
安装组件。
composer require cvcv/think-openapi在控制器与校验器上添加注解。
use Cvcv\ThinkOpenApi\Attribute\ApiDoc;访问文档路由查看生成的接口页面。
php think run --host 0.0.0.0 --port 8000截图与演示说明
本页配图采用 GitHub 仓库社交分享卡片，展示组件名称与文档生成定位。
README 以代码示例为主，展示控制器注解与校验器复用的写法。
组件为开发工具类库，无运行界面截图，效果以生成产物与注解示例说明。
常见问题
问. Think OpenAPI 是什么
一套面向 ThinkPHP 8 的 OpenAPI 3.1 文档生成器与 UI 组件源码。
问. 必须 ThinkPHP 8 吗
组件按 ThinkPHP 8 设计，其他版本请自行评估兼容性。
问. 已有 swagger-php 项目能迁移吗
文档结构通用，注解需按本组件语法改写。
问. 可以商用吗
采用 MIT 协议发布，保留版权与协议声明即可自由使用。
安全风险提示
文档页面请勿在生产环境对公网开放，避免接口结构泄露。
注解信息请与实际实现保持同步，防止误导调用方。
项目采用 MIT 协议开源，商用保留版权与协议声明即可。
接入后请跟进仓库的后续版本更新，及时获取问题修复与功能改进。
使用中遇到问题可在仓库 issue 区反馈，附上复现步骤便于定位。
下载说明
本页提供 ThinkPHP 接口文档组件完整源码打包下载，含组件代码与注解示例。
压缩包内含完整组件代码、双语文档与使用示例，解压后按 README 步骤安装依赖即可接入现有项目运行。
GitHub项目开源地址 https://github.com/c-v-c-v/think-openapi
