Flutter书架开放接口插件shelf_open_api的使用

Shelf Open Api

这个库的目的是从你的shelf控制器生成包含开放API规范的文件。 OpenApi Specification 是一个用于描述 RESTful API 的标准。

特性

• ✅ Info (版本控制、端点等API信息)
• ✅ Params (仅支持字符串类型的参数)
• ✅ Requests
• ✅ Responses
• ❌ 错误响应
• ✅ 通过 $ref 引用的重用模式
• ❌ 不支持继承和多态性（通过 allOf, oneOf, anyOf, discriminator）
• ❌ 不支持 json_serializable 注解
• [-] 安全性（部分实现）
• ✅ 文档（summary, description, example）
• ✅ 标签/分组
• ❌ 不支持通过 @Deprecated() 元注解标记为废弃的操作
• ❌ 不支持默认值 default

安装包

要使用 shelf_open_api，你需要典型的 build_runner/代码生成设置。首先，在你的 pubspec.yaml 文件中添加以下依赖：

# pubspec.yaml
dependencies:
  shelf_open_api:

dev_dependencies:
  build_runner:
  shelf_open_api_generator:

使用

你可以在 example 文件夹中查看一些示例。

创建一个以 *.open_api.dart 结尾的库文件。你可以写任何你想要的内容，例如：

final openApi = 'place holder for shelf_open_api_generator package';

运行代码生成器，你可以使用以下命令：

• <dart|flutter> pub run build_runner build

完成后，你将看到生成的文件。现在让我们定义路由！

在需要定义查询类型或请求体类型的路由上使用 OpenApiRoute。记住，你可以为每个路由定义摘要和描述。摘要必须是一行，否则它将成为你的路由描述。

JsonResponse 类可以在示例中找到。是否应该将其添加到 shelf_open_api 包中？

class MessagesController {
  @Route.get('/messages')
  @OpenApiRoute(requestQuery: MessageFetchDto)
  Future<JsonResponse<void>> fetch(Request request) async {
    // 代码...
  }

  /// 这是一个摘要
  ///
  /// 这是一个
  /// 长描述
  @Route.post('/messages')
  @OpenApiRoute(requestBody: MessageCreateDto)
  Future<JsonResponse<void>> create(Request request) async {
    // 代码...
  }
}

你也可以为你的查询或请求定义摘要、描述和示例：

class MessageCreateDto {
  /// 聊天的ID，消息将发送到此聊天。
  final String chatId;
  /// 消息的内容。
  ///
  /// 你可以输入文本和表情符号。不支持图片。
  ///
  /// `嗨，路易吉！`
  final String content;

  const MessageCreateDto({
    required this.chatId,
    required this.content,
  });
}

选项

你可以在 config 文件中找到许多其他配置参数。

targets:
  $default:
    builders:
      shelf_open_api_generator:
        options:
          include_routes_in: 'lib/**_controller.dart'
          info_title: 'Api'
          security_schemes:
             appwriteJwt:
               type: http
               scheme: Bearer
               bearerFormat: JWT

Shelf路由

如果你的应用中有太多控制器，这可能会帮助你！

使用 Routing 并编写一个包含应用中所有控制器的文件。

@Routing(
  varName: 'controllersRouter',
  generateFor: ['**/*_controller.dart'],
)
void main() {
  // ...
}

// *.g.dart

import 'package:shelf_router/shelf_router.dart';
import 'package:app/features/chats/controllers/chats_controller.dart';
import 'package:app/features/messages/controllers/messages_controller.dart';
import 'package:app/features/users/controllers/users_controller.dart';

final $controllersRouter = Router()
  ..mount('/v1', UsersController().router)
  ..mount('/v1', MessagesController().router)
  ..mount('/v1', ChatsController().router);

这允许你使用 @Routes(prefix: '/v1') 来前缀所有控制器路由。此注解不是强制性的。

@Routes(prefix: '/v1')
class MessagesController {
  // ...
}

选项

targets:
  $default:
    builders:
      shelf_open_api_generator:shelf_routing:
        generate_for:
          - '**/*_api.dart'