Flutter文档生成插件dartdoc_json的使用

Flutter文档生成插件dartdoc_json的使用

安装

dart pub global activate dartdoc_json

使用

dartdoc_json FILENAME(s)

输出

生成的JSON文件将具有以下结构：

{
  "root": [
    {
      "compilationUnit": {
        "source": "输入文件名",
        "directives": [
          {
            "kind": "import/export/part/part-of/library",
            "uri": "导入/导出文件路径",
            "show": ["符号列表"],
            "hide": ["隐藏符号列表"],
            "as": "别名",
            "name": "库名称",
            "augmentation": false
          }
        ],
        "declarations": [
          {
            "kind": "class/mixin/extension/variable/typedef/enum/function/constructor/field/getter/setter/method",
            "name": "声明名称",
            "description": "描述",
            "typeParameters": ["类型参数列表"],
            "annotations": ["注解列表"],
            "members": ["成员列表"],
            "extends": "继承类",
            "with": ["扩展类列表"],
            "implements": ["实现类列表"],
            "on": ["混入类列表"],
            "parameters": ["参数列表"],
            "returns": "返回值类型",
            "abstract": true/false,
            "const": true/false,
            "factory": true/false,
            "static": true/false,
            "final": true/false,
            "late": true/false,
            "extraNames": ["额外名称列表"]
          }
        ]
      }
    }
  ]
}

额外的命令行选项

  • --output FILE: 指定输出文件名，默认为"out.json"
  • --root DIR: 指定根目录，所有输入文件将根据此目录查找。source字段将包含输入文件名，不包含根目录。
  • --pretty: 增加空白字符以提高可读性，但会增加文件大小。

示例代码

# 安装插件
dart pub global activate dartdoc_json

# 使用示例
dartdoc_json example.dart

示例输出

{
  "root": [
    {
      "compilationUnit": {
        "source": "example.dart",
        "directive": [
          {
            "kind": "import",
            "uri": "path/to/another/file.dart",
            "show": ["symbol1", "symbol2"],
            "hide": [],
            "as": "alias",
            "name": "library_name",
            "augmentation": false
          },
          {
            "kind": "export",
            "uri": "path/to/another/file.dart",
            "show": ["symbol1", "symbol e"],
            "hide": [],
            "as": null,
            "name": "library_name",
            "augmentation": false
          }
        ],
        "declarations": [
          {
            "kind": "class",
            "name": "MyClass",
            "description": "这是一个类的描述。",
            "typeParameters": [],
            "annotations": [],
            "members": [
              {
                "kind": "method",
                "name": "myMethod",
                "description": "这是一个方法的描述。",
                "parameters": [
                  {
                    "name": "param1",
                    "type": "int",
                    "default": null,
                    "covariant": false,
                    "required": false
                  },
                  {
                    "name": "param2",
                    "type": "String",
                    "default": null,
                    "covariant": false,
                    "required": true
                  }
                ],
                "returns": "void"
              }
            ],
            "extends": null,
            "with": [],
            "implements": [],
            "on": [],
            "abstract": false,
            "const": false,
            "factory": false,
            "static": false,
            "final": false,
            "late": false,
            "extraNames": []
          }
        ]
      }
    }
  ]
}

更多关于Flutter文档生成插件dartdoc_json的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter文档生成插件dartdoc_json的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


当然，以下是如何在Flutter项目中使用dartdoc_json插件来生成文档并以JSON格式输出的相关代码和步骤。dartdoc_json是dartdoc的一个变体，它生成JSON格式的API文档，而不是HTML。

1. 添加依赖

首先，在你的pubspec.yaml文件中添加dartdoc_json依赖。由于dartdoc_json并不是pub.dev上的官方包，你需要直接从GitHub或其他源获取它。这里假设你已经克隆了dartdoc_json的仓库并将其作为本地依赖添加：

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  dartdoc_json:
    path: ../path/to/dartdoc_json  # 指向你本地dartdoc_json克隆仓库的路径

2. 配置dartdoc_json

在项目的根目录下创建一个dartdoc_options.yaml文件来配置dartdoc_json。以下是一个简单的配置示例：

include:
  - lib/**.dart

exclude:
  - lib/generated/**.dart

output: doc/api_docs.json

这个配置告诉dartdoc_json只包含lib目录下的Dart文件，排除lib/generated目录，并将输出写入doc/api_docs.json文件。

3. 生成JSON文档

你可以通过命令行运行dartdoc_json。假设你已经将dartdoc_json的bin/dartdoc.dart脚本路径添加到了你的PATH中，或者你可以直接使用相对路径运行它。

在项目的根目录下打开终端，运行以下命令：

dart ../path/to/dartdoc_json/bin/dartdoc.dart --input lib --output doc/api_docs.json

这里--input指定了要生成文档的Dart文件目录（通常是lib），--output指定了输出JSON文件的路径。

4. 自动化（可选）

为了自动化这个过程，你可以在pubspec.yaml中添加一个脚本命令：

scripts:
  generate_docs: dart ../path/to/dartdoc_json/bin/dartdoc.dart --input lib --output doc/api_docs.json

然后你可以通过运行以下命令来生成文档：

flutter pub run generate_docs

5. 解析和使用生成的JSON文档

生成的JSON文档可以很容易地被解析和使用。以下是一个简单的Dart脚本示例，展示如何读取和解析这个JSON文件：

import 'dart:convert';
import 'dart:io';

void main() async {
  File file = File('doc/api_docs.json');
  String contents = await file.readAsString();
  Map<String, dynamic> jsonData = jsonDecode(contents);

  // 在这里你可以遍历jsonData，根据你的需求处理数据
  print(jsonData);
}

这个脚本读取生成的api_docs.json文件，并将其内容解析为一个Dart的Map对象，然后你可以遍历这个Map来访问和处理API文档数据。

注意

  • 由于dartdoc_json可能不是官方维护的包，使用时需要注意其兼容性和更新情况。
  • 确保你的Dart环境是最新的，因为dartdoc和相关的工具链可能会依赖于较新的Dart特性。
  • 如果dartdoc_json有特定的配置需求或命令行参数，请参考其仓库的README文件或源代码。

希望这能帮助你在Flutter项目中成功使用dartdoc_json生成JSON格式的API文档！

回到顶部