Next API Reference Generator

注意：此软件包处于开发阶段，处于非常初级的阶段。您可能会遇到错误。如果您遇到，请提出问题或创建一个PR。

本项目旨在生成 NextJS 13 中找到的 路由处理程序 的API参考。

目前目标是提供至少2个生成器

• JSON
• 静态HTML参考

随着工作的进行，文档将不断更新。

Usage: next_api_reference [OPTIONS] --output <OUTPUT>

Options:
  -v, --verbose              Enable verbose logging
  -l, --location <LOCATION>  Location to find route handlers from [default: ./]
  -o, --output <OUTPUT>      The directory to output to
  -j, --json
  -h, --help                 Print help
  -V, --version              Print version

目标

• 基本的JSON生成器。
• 基本的HTML生成器。
• 解析注释以将文档添加到API端点。
• 实现基本日志记录。
• 更好的注释解析。

HTML生成器（默认）

HTML生成器是默认生成器。它输出一个基本的静态网站，可以根据需要修改。

生成器 不能 在同一位置使用文件，如果您的站点已进行修改。

示例命令

next_api_reference -v -l ./app -o ./output

JSON生成器

JSON生成器将API参考输出到JSON文件。它适用于您想编写自己的API参考网站的情况。您可以使用此生成器生成数据，并将其解析以创建符合您需求的参考网站。

示例命令

next_api_reference -l ./app -o ./output -j

-j 标志是使用JSON生成器的必要条件。

模式

{
  "$schema": "https://json-schema.fullstack.org.cn/draft-07/schema#",
  "title": "Schema for next_api_reference json generator",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string"
      },
      "method_metadata": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "method_type": {
              "type": "string"
            },
            "comment": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": ["method_type"]
        }
      }
    },
    "required": ["path", "method_metadata"]
  }
}

示例输出

[
  {
    "path": "/api/items",
    "method_metadata": [
      {
        "method_type": "GET",
        "comment": ["Get a list of all items"]
      },
      {
        "method_type": "POST",
        "comment": ["Create an item"]
      },
      {
        "method_type": "DELETE",
        "comment": ["Delete an item or a list of items"]
      }
    ]
  },
  {
    "path": "/api/items/count",
    "method_metadata": [
      {
        "method_type": "GET",
        "comment": ["Get a count of all items"]
      }
    ]
  }
]

文档字符串

此软件包支持文档字符串解析。然而，目前还不够完善。

支持的模式

要创建文档字符串，只需在函数定义上方创建单行注释

// This is a simple docstring
export async function GET(request: Request) {}

块注释在HTML生成器中的行为可能因生成器而异。对于HTML生成器，只显示第一行，而对于JSON生成器，则提供整个字符串的原始形式，可能需要进行一些额外的处理。

HTML生成器中的块注释行为可能在将来发生变化。

不支持的模式

遗憾的是，对于类似这样的内容，目前不支持文档字符串解析，文档字符串将被忽略。

// This is a simple docstring
async function GET(request: Request) {}

export { GET };

贡献

如果您在此项目中发现缺少您需要的特性或存在错误，请检查是否已创建相关的问题，如果没有，请创建一个问题。

为项目做出贡献很简单

1. 复制仓库
2. 创建一个新分支
3. 施展你的魔法
4. 提交PR

如果此项目变得流行，未来将创建更好的工作流程和指南。