Flutter API指南插件api_guide的潜在功能使用

概览

api_guide是一个Flutter包，用于生成类似于OpenAPI模式的API调用文档。它能够帮助开发者为HTTP请求（如Get、Post、Put、Delete或Options）和响应创建详细的文档说明。

功能特性 ✨

• 支持复制示例代码到剪贴板。
• 响应式设计适配不同屏幕尺寸。
• 提供浅色和深色主题模式。
• 快速搜索工具支持键盘快捷键。
• 可自定义的简介部分。
• 无限FAQ部分，可添加任意数量的问题与答案。
• 平滑滚动的侧边栏。
• 显示版本号及最后更新日期。
• 可选的隐私政策和使用条款链接。
• 生成的代码模型覆盖30+种代码片段类型，并支持多服务器。
• 支持400+种SPDX许可证类型的链接。
• 可选的主题颜色变更，支持10+种颜色分布。
• 支持15+种Web API标准安全方案。
• 在介绍部分、API项描述和FAQs回答中支持Markdown格式。
• 遵循W3C、OpenAPI Schema和RFCs标准构建。

安装 ⏳

要开始使用api_guide，请按照以下步骤操作：

1. 在pubspec.yaml文件中添加依赖：

   dependencies:
     api_guide: ^1.1.8
   

2. 导入到项目中：

   import 'package:api_guide/api_guide.dart';
   

3. 在目标网页中使用APIGuide().display()方法并传递必要的参数。

使用示例 ✅

下面是一个完整的使用示例，展示了如何将api_guide集成到您的Flutter应用中。

import 'package:api_guide/api_guide.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Flutter API Guide Example',
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return APIGuide().display(
      context: context,
      version: 1.0,
      latestUpdate: DateTime.parse('2023-10-10'),
      apiIntro: 'This is some introduction to API Guide.',
      apiItems: _apiItems,
      servers: [
        const APIServer(urlHost: 'https://example.com'),
      ],
      apiFaqs: [
        APIGuideFAQ(question: 'Can Dash Fly?', answer: 'Yes, Dash can Fly.'),
      ],
    );
  }
}

List<APIItem> _apiItems = [
  APIItem(
    title: 'All Dashes',
    urlPath: '/dashes',
    description: 'All Dashes get example description.',
    request: APIGuideRequest(method: HttpRequestMethod.GET),
    response: [
      const APIGuideResponse(
        statusCode: HttpResponseStatusCode.OK,
        body: {"status": 200, "data": {"name": "Dash", "isFly": true}},
      ),
    ],
  ),
  APIItem(
    title: 'Create',
    urlPath: '/create',
    description: 'Store Dash post example description.',
    request: APIGuideRequest(
      method: HttpRequestMethod.POST,
      body: [
        const APIGuideRequestBody(
          key: 'name',
          value: 'Dash',
          type: PropertyType.string,
          description: 'This is the name attribute.',
          isRequired: true,
        ),
        const APIGuideRequestBody(
          key: 'isFly',
          value: true,
          type: PropertyType.boolean,
          description: 'This is the isFly attribute.',
          isRequired: true,
        ),
      ],
    ),
    response: [
      const APIGuideResponse(
        statusCode: HttpResponseStatusCode.OK,
        body: {"status": 200, "data": {"message": "Data Stored Successfully."}},
      ),
      const APIGuideResponse(
        statusCode: HttpResponseStatusCode.BadRequest,
        body: {"status": 400, "data": {"message": "Error Data Not Stored!"}},
      ),
    ],
  ),
];

注意事项 📝

• 将MaterialApp中的debugShowCheckedModeBanner设置为false以隐藏调试模式下的红色条带。
• 如果您在Scaffold内添加了APIGuide().display()组件，请确保将其放在body属性中，不要放在appBar、drawer、floatingActionButton、bottomNavigationBar或bottomSheet中，因为它本身已经包含了作为完整页面所需的Scaffold。
• 推荐直接在StatelessWidget的build方法中返回APIGuide().display()作为其值。
• 如果未设置termsLink或privacyLink，它们将不会显示。
• 如果未指定themeColor，它将默认使用APIGuideThemeColor.indigo配色方案。
• 内部函数属性（如APIItem.isHovered、APIItem.isOptionalSecurity等）是自动调整的，因此即使传递也不会影响功能。

如果您在使用过程中遇到任何问题或者有其他需求，欢迎查阅官方GitHub仓库获取更多信息和支持。感谢您对api_guide的关注和支持！🎉