API 文档 — Swagger

Finch 内置 OpenAPI/Swagger 文档生成器。直接在 Dart 代码中为端点添加注解。

设置

1. 创建 ApiController

import 'package:finch/finch_route.dart';

class UserApiController extends ApiController {
  @override
  String get apiTitle => '用户 API';

  @override
  String get apiVersion => '1.0.0';

  @ApiDoc(
    summary: '获取所有用户',
    description: '返回所有活跃用户的列表',
    parameters: [
      ApiParameter(name: 'page',  in_: 'query', type: 'integer'),
      ApiParameter(name: 'limit', in_: 'query', type: 'integer'),
    ],
    responses: [
      ApiResponse(statusCode: 200, description: '成功'),
      ApiResponse(statusCode: 401, description: '未认证'),
    ],
  )
  Future<String> getUsers() async {
    // ...
    return rq.renderData(data: users);
  }
}

2. 注册路由

router.get('/api/users', UserApiController().getUsers);

3. 连接 ApiDoc

FinchConfigs(
  enableApiDoc: true,
  apiDocPath: '/api/docs',
)

文档 UI 可在 /api/docs 访问。

ApiParameter

ApiResponse

ApiResponse(
  statusCode: 201,
  description: '用户已创建',
  schema: {'type': 'object', 'properties': {'id': {'type': 'integer'}}},
)

预定义快捷方式

Finch 提供简化注解：

@ApiGet(summary: '获取项目')
@ApiPost(summary: '创建项目')
@ApiPut(summary: '更新项目')
@ApiDelete(summary: '删除项目')