dcatpus-admin 开放接口文档系统

• 官方网站

• 中文文档

• github

• Demo/在线演示

• 示例源码

• 技术社区

Dcatplus-Admin 是一个基于 Laravel 的高效后台开发框架，以极简代码、丰富组件和优雅的界面设计，快速构建功能完善的后台管理系统(非前后端分离)。无需花费更多时间 学习掌握其它技术栈，就能快速构建交付你的项目。

dcatplus-admin 1.4.2 后开始支持开放接口功能 查看演示 Laravel12 + dcatplus-admin(1.4.2)

1. 特色功能

本系统基于 dcatplus-admin 代码生成器与 dedoc/scramble 深度整合，提供以下核心特色：

• 自动化接口生成：根据数据表结构自动生成 RESTful API

• 多端隔离：支持多模块接口独立管理（管理端/商家端/用户端）

• 注释即文档：采用 OpenAPI 3.0 规范，代码注释自动生成文档

• 可视化调试：内置 API 调试工具，支持在线测试接口

• 权限集成：与 dcat-admin 权限系统无缝对接

• 版本管理：支持接口版本控制与历史记录查看

2. 接口模块划分（已自带授权）

系统包含以下独立接口模块：

| 模块名称 | 访问前缀 | 说明 |

|------------|-------------|-------------------------|

| admin-api | /admin-api | 平台管理端接口（超级管理员使用） |

| member-api | /member-api | 用户端接口（客户端用户使用） |

3. 文档系统特色

3.1 智能解析

• 自动识别路由参数、请求方法、响应结构

• 支持 JSON/XML 等多种响应格式展示

• 自动提取验证规则生成参数校验说明

3.3 文档配置

config/scramble.php 配置 也可直接查看scramble官方文档 >> 查看

 <?php use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess; return [ /* * API 基础路径。默认情况下，所有以此路径开头的路由都将被添加到文档中。 * 如需自定义此行为，可以使用`Scramble::routes()`添加自定义路由解析器。 */ 'api_path' => 'api', /* * API 域名。默认使用应用域名。这也是默认 API 路由匹配器的一部分， * 如果自行实现路由匹配器，请确保在需要时使用此配置。 */ 'api_domain' => null, /* * OpenAPI 规范文件的导出路径。 */ 'export_path' => 'api.json', 'info' => [ /* * API 版本号。 */ 'version' => env('API_VERSION', '0.0.1'), /* * 在 API 文档首页(`/docs/api`)显示的描述文本。 */ 'description' => '用户端 Api 文档', ], /* * 自定义 Stoplight Elements UI */ 'ui' => [ /* * 文档网站的标题。为 null 时使用应用名称。 */ 'title' => '用户端 Api 文档', /* * 文档主题。可选值为`light`和`dark`。 */ 'theme' => 'light', /* * 隐藏"Try It"功能。默认启用。 */ 'hide_try_it' => false, /* * 在目录中隐藏 Schema 。默认启用。 */ 'hide_schemas' => false, /* * 显示在标题旁边的小型方形 logo 图片 URL ，位于目录上方。 */ 'logo' => '', /* * 控制"Try It"功能的凭证策略。可选值：omit(忽略)、include(包含，默认)、same-origin(同源) */ 'try_it_credentials_policy' => 'include', /* * Elements 提供的三种布局： * - sidebar (Elements 默认)：三栏设计，带有可调整大小的侧边栏 * - responsive：类似 sidebar ，但在小屏幕下会将侧边栏折叠为可切换的抽屉式菜单 * - stacked：单栏布局，适合已自带侧边栏的现有网站集成 */ 'layout' => 'responsive', ], /* * API 服务器列表。默认 null 时，服务器 URL 会根据`scramble.api_path`和`scramble.api_domain`配置自动生成。 * 如果提供数组，则需要手动指定本地服务器 URL(如果需要)。 * * 非默认配置示例(最终 URL 使用 Laravel 的`url`辅助函数生成): * * ```php * 'servers' => [ * 'Live' => 'api', * 'Prod' => 'https://scramble.dedoc.co/api', * ], * ``` */ 'servers' => null, /** * 控制 Scramble 如何存储枚举用例的描述。 * 可用选项： * - 'description'：将用例描述存储为枚举 Schema 的描述(使用表格格式) * - 'extension'：将用例描述存储在枚举 Schema 的`x-enumDescriptions`扩展中 * * @see https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-enum-descriptions * - false：忽略枚举用例描述 */ 'enum_cases_description_strategy' => 'description', 'middleware' => [ 'web', RestrictedDocsAccess::class, ], 'extensions' => [ ], ]; 

3.4 生成多个文档

例如：需要生成一个 商家端 api 文档. 文档访问的地址是： http://www.xxx.com/docs/store-api#/

在 app/Providers/AppServiceProvider.php 的 boot 方法中添加如下代码

 // 注册 store-api 文档 $store_api_path = config('admin.openapi.store-api.api_path','store-api'); // 可以从配置文件中获取 \Dedoc\Scramble\Scramble::registerApi($store_api_path, [ 'api_path' => $store_api_path, 'info' => [ 'version' => config('admin.openapi.store-api.info.version','1.0.0'), 'description' => config('admin.openapi.store-api.info.description','管理端 api 文档'), ], 'servers' => [ 'Local' => $store_api_path, // 本地环境 'Prod'=> env('APP_API_URL').'/'.$store_api_path, // 线上环境 ], 'ui' => [ 'title' => config('admin.openapi.store-api.ui.title','B 端 Api 文档'), ] ])->withDocumentTransformers(function (OpenApi $openApi) { $openApi->secure( SecurityScheme::http('Bearer','JWT') ); }); // 注册 api 路由 \Dedoc\Scramble\Scramble::registerUiRoute('docs/'.$store_api_path,$store_api_path); \Dedoc\Scramble\Scramble::registerJsonSpecificationRoute('docs/'.$store_api_path.'json', $store_api_path); // 配置 Scramble::configure() ->withDocumentTransformers(function (OpenApi $openApi) { $openApi->secure( SecurityScheme::http('Bearer','JWT') ); }); 

3.4.1 生成多个文档的呈现效果预览

3.5 交互式文档

 use App\Models\StoreUser; use Dedoc\Scramble\Attributes\QueryParameter; use Dedoc\Scramble\Attributes\BodyParameter; use Dedoc\Scramble\Attributes\Group; #[Group('授权','用户授权',1)] class StoreAuthController extends Controller { /** * 门店登陆 * 通过门店编号和密码获取 token * @unauthenticated * @operationId storeLogin */ public function login(Request $request){ $request->validate( [ /** * 门店编号 *@default 1000003 */ 'username' => ['required','string','min:3','max:20',Rule::exists(StoreUser::class, 'username')], /** * 登陆密码 * @default 12345678 */ 'password' => ['required','string','min:6','max:20'], ], [ 'username.required' => '请填写用户名', 'username.min' => '用户名长度不能小于 3 个字符', 'username.max' => '用户名长度不能大于 20 个字符', 'username.exists' => '用户名不存在', 'password.required' => '请填写密码', 'password.min' => '密码长度不能小于 6 个字符', 'password.max' => '密码长度不能大于 20 个字符', ] ); }