Flutter API文档生成插件swagger_generator的使用

Flutter API文档生成插件swagger_generator的使用

swagger_generator 是一个利用 dio 拦截器自动生成 swagger 结构的库。使用它能够轻松地创建 API 文档，减少工作量。

特性

• 库的模型基于 Swagger 基本结构。
• 自动创建 swagger 路径、标签、请求体、请求响应等，并保存到 swagger.json 文件中。
• 可以预览 swagger.json 文件。
• 自动保存到本地并合并更新过的请求/响应数据。
• 同步数据到 GitLab 以便在 Swagger Hub 中查看。
• 库会忽略基础 URL 在 servers 之外的请求。

入门指南

配置拦截器

将此库添加到 dio 的拦截器中。为了避免由于拦截器未记录完整响应而导致重定向，应将此拦截器放置在认证拦截器和错误拦截器之间。

Dio()
..interceptors.addAll([
    AuthInterceptor(),
    SwaggerInterceptor(),
    ErrorInterceptor(),
]);

1. 初始化插件

[必需]

SwaggerGenerator.instance.initial(
    Swagger(
      id: '1',
      info: const SwaggerInfo(
        title: 'Example API docs',
        version: '1.0.0',
      ),
      servers: const [
        SwaggerServer(
          url: 'https://example.swagger-test/api/v1',
          description: 'Test',
        ),
      ],
      components: SwaggerComponent(
        securities: const [
          SwaggerSecurity(
            name: 'Authorization',
            type: 'http',
            scheme: 'bearer',
            bearerFormat: 'JWT',
          ),
          SwaggerSecurity(
            name: 'Device-Type',
            type: 'apiKey',
          ),
        ],
      ),
    ),
    includeResponse: true,
  );

2. 使用额外选项为路径添加详细信息

定义路径参数

默认情况下，库会从路径中提取查询参数。例如执行路径 /posts/1/comments，则 swagger 路径将被创建为 "/posts/{postId}/comments"。如果你希望自定义，可以在 dio 请求的选项中添加它。

final resp = await _dio.get(
      '/posts/1/comments',
      options: Options(
        extra: {
          'path': 'posts/{myPostId}/comments',
        },
      ),
    );

另一种方法是通过传递 pathParamsRegs 当调用 initial 时定义正则表达式规则来提取查询参数。

定义摘要或描述

同样可以使用额外选项来定义摘要或描述。

final resp = await _dio.get(
      '/posts/1/comments',
      options: Options(
        extra: {
          'summary': 'Summary of this API',
          'description': 'This API executes an action',
        },
      ),
    );

3. 预览数据

库支持预览 JSON 数据。你可以复制 JSON 内容或将最新结构同步到 GitLab。可以通过以下方式导航：

SwaggerGenerator.instance.openPreviewPage(context);

4. 同步到 GitLab

输入你的 GitLab 信息后，可以同步最新结构到 GitLab。

示例

请参阅示例：/example

示例代码

import 'package:dio/dio.dart';
import 'package:example/auth_interceptor.dart';
import 'package:example/error_interceptor.dart';
import 'package:flutter/material.dart';
import 'package:swagger_generator/swagger_generator.dart';

const baseUrl = 'https://jsonplaceholder.typicode.com';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  SwaggerGenerator.instance.initial(
    Swagger(
      id: '1',
      info: const SwaggerInfo(
        title: 'Example API docs',
        version: '1.0.0',
      ),
      servers: const [
        SwaggerServer(
          url: baseUrl,
          description: 'Json placeholder',
        ),
      ],
      components: SwaggerComponent(
        securities: const [
          SwaggerSecurity(
            name: 'Authorization',
            type: 'http',
            scheme: 'bearer',
            bearerFormat: 'JWT',
          ),
        ],
      ),
    ),
    includeResponse: true,
  );
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  [@override](/user/override)
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Swagger Generator Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'Swagger Generator Demo'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late final Dio _dio;

  [@override](/user/override)
  void initState() {
    _dio = Dio()
      ..options.baseUrl = baseUrl
      ..options.contentType = 'application/json'
      ..interceptors.addAll(
        [
          AuthInterceptor(),
          SwaggerInterceptor(),
          ErrorInterceptor(),
        ],
      );
    super.initState();
  }

  Future<void> _fetchPost() async {
    final resp = await _dio.get('/posts/1/comments');
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(
      content: Text('We have ${(resp.data as List).length} post'),
      behavior: SnackBarBehavior.floating,
    ));
  }

  Future<void> _fetchCommentByPost() async {
    final resp = await _dio.get(
      '/comments?postId=1',
      options: Options(
        extra: {
          'summary': 'Get comments in a post',
          'description': 'Get comments in a post by passing a postId'
        },
      ),
    );
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(
      content: Text('We have ${(resp.data as List).length} comments in post 1'),
      behavior: SnackBarBehavior.floating,
    ));
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ElevatedButton(
              onPressed: () {
                _fetchPost();
              },
              child: const Text('Get all posts'),
            ),
            ElevatedButton(
              onPressed: () {
                _fetchCommentByPost();
              },
              child: const Text('Get comments by postId'),
            )
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => SwaggerGenerator.instance.openPreviewPage(context),
        child: const Icon(Icons.window),
      ),
    );
  }
}