---
name: backend-route
description: Generate route configuration for madong module. Supports both app (main project) and plugin targets. Creates route.php files for adminapi and api with proper OpenAPI scan paths.
---

# Generate Route

Create route configuration files for modules.

## File Location

**App (主项目):**
```
app/adminapi/config/route.php
app/api/config/route.php
```

**Plugin (插件):**
```
plugin/{plugin}/config/route.php
```

## AdminAPI Route Template

```php
<?php

declare(strict_types=1);
/**
 *+------------------
 * madong
 *+------------------
 * Copyright (c) https://gitee.com/motion-code All rights reserved.
 *+------------------
 * Author: Mr. April (405784684@qq.com)
 *+------------------
 */

use Webman\Route;
use WebmanTech\Swagger\Swagger;
use OpenApi\Annotations as OA;

/**
 * 注册admin API路由
 */
Route::group('/adminapi', function () {
    Swagger::create()->registerRoute([
        'route_prefix'   => '/openapi',
        'register_route' => true,
        'openapi_doc'    => [
            'scan_path' => [
                base_path('app/schema'),      // 基础schema
                base_path('app/adminapi'),
                base_path('app/install'),
            ],
            'modify'    => function (OA\OpenApi $openapi) {
                $openapi->info->title   = config('app.name') . ' API';
                $openapi->info->version = '1.0.0';
                $openapi->servers       = [
                    new OA\Server([
                        'url'         => '/adminapi',
                        'description' => request()->host(),
                    ]),
                ];

                if (!$openapi->components instanceof OA\Components) {
                    $openapi->components = new OA\Components([]);
                }

                $openapi->components->securitySchemes = [
                    new OA\SecurityScheme([
                        'securityScheme' => 'api_key',
                        'type'           => 'apiKey',
                        'name'           => config('madong.jwt.app.token_name', 'Authorization'),
                        'in'             => 'header',
                    ]),
                ];
            },
        ],
    ]);
});
```

## API Route Template

```php
<?php

declare(strict_types=1);
/**
 *+------------------
 * madong
 *+------------------
 * Copyright (c) https://gitee.com/motion-code All rights reserved.
 *+------------------
 * Author: Mr. April (405784684@qq.com)
 *+------------------
 */

use Webman\Route;
use WebmanTech\Swagger\Swagger;
use OpenApi\Annotations as OA;

/**
 * 注册API路由
 */
Route::group('/api', function () {
    Swagger::create()->registerRoute([
        'route_prefix'   => '/openapi',
        'register_route' => true,
        'openapi_doc'    => [
            'scan_path' => [
                base_path('app/api'),
            ],
            'modify'    => function (OA\OpenApi $openapi) {
                $openapi->info->title   = config('app.name') . ' API';
                $openapi->info->version = '1.0.0';
                $openapi->servers       = [
                    new OA\Server([
                        'url'         => '/api',
                        'description' => request()->host(),
                    ]),
                ];

                if (!$openapi->components instanceof OA\Components) {
                    $openapi->components = new OA\Components([]);
                }

                $openapi->components->securitySchemes = [
                    new OA\SecurityScheme([
                        'securityScheme' => 'api_key',
                        'type'           => 'apiKey',
                        'name'           => config('core.jwt.app.token_name', 'Authorization'),
                        'in'             => 'header',
                    ]),
                ];
            },
        ],
    ]);
});
```

## Plugin Route Template

```php
<?php

declare(strict_types=1);
/**
 *+------------------
 * madong
 *+------------------
 * Copyright (c) https://gitee.com/motion-code All rights reserved.
 *+------------------
 * Author: Mr. April (405784684@qq.com)
 *+------------------
 */

use Webman\Route;
use WebmanTech\Swagger\Swagger;
use OpenApi\Annotations as OA;

/**
 * 注册{Plugin}插件路由
 */
Route::group('/{plugin_path}', function () {
    // AdminAPI 路由
    Route::group('/adminapi', function () {
        // 控制器自动加载，无需手动注册
    });

    // API 路由
    Route::group('/api', function () {
        // 控制器自动加载，无需手动注册
    });

    // Swagger 文档注册
    Swagger::create()->registerRoute([
        'route_prefix'   => '/openapi',
        'register_route' => true,
        'openapi_doc'    => [
            'scan_path' => [
                // 插件的 adminapi 目录
                __DIR__ . '/app/adminapi',
                // 插件的 api 目录
                __DIR__ . '/app/api',
            ],
            'modify'    => function (OA\OpenApi $openapi) {
                $openapi->info->title   = '{Plugin} API';
                $openapi->info->version = '1.0.0';
                $openapi->servers       = [
                    new OA\Server([
                        'url'         => '/{plugin_path}',
                        'description' => request()->host(),
                    ]),
                ];

                if (!$openapi->components instanceof OA\Components) {
                    $openapi->components = new OA\Components([]);
                }

                $openapi->components->securitySchemes = [
                    new OA\SecurityScheme([
                        'securityScheme' => 'api_key',
                        'type'           => 'apiKey',
                        'name'           => config('madong.jwt.app.token_name', 'Authorization'),
                        'in'             => 'header',
                    ]),
                ];
            },
        ],
    ]);
});
```

## Route Auto-Discovery

Controllers are auto-loaded by webman based on naming convention:

| Controller | Auto Route |
|------------|------------|
| `adminapi/controller/member/MemberController.php` | `/adminapi/member/member` |
| `adminapi/controller/member/UserController.php` | `/adminapi/member/user` |
| `api/controller/auth/AuthController.php` | `/api/auth/auth` |

### Route Naming Convention

```
app/adminapi/controller/{module}/{Model}Controller.php
                                    ↓
                          /{module}/{model}
```

## Swagger Scan Path Configuration

### AdminAPI OpenAPI Scan

```php
'scan_path' => [
    base_path('app/schema'),      // Schema DTOs
    base_path('app/adminapi'),    // AdminAPI controllers, validates
    base_path('app/install'),     // Install controllers
],
```

### API OpenAPI Scan

```php
'scan_path' => [
    base_path('app/api'),         // API controllers
],
```

## Custom OpenAPI JSON Endpoint

When the project requires the Swagger UI to load `/openapi.json` instead of the package default `/openapi/doc`, do not modify `vendor/webman-tech/swagger`.

Use `app\controller\OpenApiController` to render the Swagger UI and generate the JSON document with `ConfigOpenapiDocDTO` and `WebmanTech\Swagger\Overwrite\Generator`. In each API route group:

```php
$openApiController = new OpenApiController();
Route::get('/openapi', static fn () => $openApiController->index('/api/openapi.json'));
Route::get('/openapi.json', static fn () => $openApiController->document($openapiDocConfig));

$config = ConfigOpenapiDocDTO::fromConfig($openapiDocConfig);
RouteRegister::create()->register((new Reader())->getData($config->getScanSources()));
```

For Admin API, use `/adminapi/openapi.json` as the Swagger UI document URL. Keep the existing scan paths and OpenAPI `modify` callback in `$openapiDocConfig` so generated documentation and annotation route registration remain consistent.

### Plugin OpenAPI Scan

当前项目插件路由以 `plugin/{plugin}/config/route.php` 为入口，按访问端分成独立路由组。已验证的 `produce` 插件使用以下分组：

- `/api`：前台 Web 接口，扫描 `base_path('plugin/{plugin}/app/api')`。
- `/appapi`：移动端/业务端 APP 接口，扫描 `base_path('plugin/{plugin}/app/appapi')`。
- `/adminapi`：管理端接口，扫描 `base_path('plugin/{plugin}/app/adminapi')`。

为插件新增业务端接口时，不要把 APP 控制器放进 `app/api`；应放入 `plugin/{plugin}/app/appapi/controller`，并在插件路由中新增或确认 `/appapi` 分组扫描该目录。OpenAPI `servers.url` 对应设置为 `/appapi`。

```php
'scan_path' => [
    base_path('plugin/{plugin}/app/appapi'),
],
```

## Auto-generation Checklist

When generating route:
- [ ] Create adminapi/config/route.php with Swagger
- [ ] Create api/config/route.php with Swagger
- [ ] Configure scan_path to include all relevant directories
- [ ] Set correct security scheme (Authorization header)
- [ ] Configure server URL and description
- [ ] For plugins, use __DIR__ for relative paths