Flutter API生成插件shelf_open_api_generator的使用

Shelf Open Api

这个库的目的是从你的shelf控制器生成带有开放API规范的文件。 OpenApi Specification

该库正在开发中，任何帮助都欢迎。

特性

• ✅ 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 文件夹中看到一些示例。

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

• <dart|flutter> pub run build_runner build

你可以在 public 文件夹中查看生成的结果！

完成！查看选项以获取更多信息/配置。 但是现在让我们来编写路由吧！

使用 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;
  /// 消息内容。
  /// 
  /// 可以输入文本和表情符号。不支持图片。
  /// 
  /// `Hi, Luigi!`
  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 并创建一个包含应用中所有控制器的文件！

@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'