dcatplus-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辅助函数生成):

• '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 个字符',

]

);

}