ycookie:
dcatplus-admin 开放接口文档系统
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 个字符',
]
);
}
Login
