GitHub - SessionHu/json-apidoc-gen: Simple CLI tool for generating BAC document template (original) (raw)

JSON APIDoc Generator (json-apidoc-gen)

JSON APIDoc Generator is a simple command-line tool written in Haskell for generating BAC document templates from JSON inputs.

Features

• Automatic JSON Parsing: Reads and parses JSON data from standard input.
• Flexible Type Inference: Detects field types in JSON, including arrays and nested objects.
• Markdown Documentation Output: Outputs documentation templates in a human-readable Markdown format.
• Designed for API Documentation: Ideal for generating API design documents or interface descriptions.
• BAC Based: Originally designed for bilibili-API-collect

Installation

Build from Source

Dependencies:

• GHC (Glasgow Haskell Compiler)
• Cabal (for building and managing Haskell projects)

Steps:

1. Clone the repository:
   git clone https://github.com/SessionHu/json-apidoc-gen.git
   cd json-apidoc-gen
2. Build the project using Cabal:
3. Run the CLI tool:

Usage

Arguments

Usage:
  --mininal  only output `JSON Response` forms
  --help     display this help and exit
  --version  output version information and exit

JSON Input

The tool reads JSON data from the standard input. You can provide input in the following ways:

• Pipe input: echo '{"key": "value"}' | cabal run
• Read from a file: cat example.json | cabal run
• Input manually from stdin

Command Output

The tool generates a documentation template in Markdown format and outputs it to the standard output. Usually you can pipe or redirect it to another file. The typical structure includes:

• Basic information (title, URI Scheme, HTTP method, etc.)
• Field descriptions for the JSON data
• Example response data

Example

Given the following JSON data:

{ "code": 0, "msg": "0", "ttl": 1, "data": { "hello": "world", "bili": [ "qwq", "awa", "sess" ], "count": 114514 } }

The tool generates the following documentation template:

title

https://

*请求方法: *

认证方式:

URL 参数:

JSON 回复:

根对象:

data 对象:

示例:

curl -

{
  "code": 0,
  "data": {
    "bili": [
      "qwq",
      "awa",
      "sess"
    ],
    "count": 114514,
    "hello": "world"
  },
  "msg": "0",
  "ttl": 1
}

Error Handling

• If the input JSON is invalid, the tool outputs an error message to the standard error.
• If the root of the JSON is not an object, the tool will indicate the unsupported type.

Known Issues

• No i18n support, only support output in Simplified Chinese.
• No object structure check within array.
• Unrecognized object to be used as Map.

License

This project is licensed under the GNU General Public License v3.0.

Thank you for using JSON APIDoc Generator! If you encounter any issues or have suggestions for improvement, feel free to submit an Issue.