yaml-api-doc

API Documentation Generator

这是一个工具脚本，用于根据 YAML 文件和特定的 Word 格式生成 API 文档。

🌿Installation

yarn add yaml-api-doc

或

npm install yaml-api-doc

🌿Usage

将你的 YAML 文件和 Word 文本放在项目目录下。

引入 exportWordDoc 并调用：

//test.js
import exportWordDoc from "yaml-api-doc";

exportWordDoc(demoUrl, outUrl, fileName);
//demoUrl: word 模板路径
//outUrl: 输出文档路径
//fileName： yaml 文件路径
//例： exportWordDoc("in.docx", "out.docx", "openapi-resource.yaml");

运行 test.js ，生成的 API 文档将会写入到 outUrl 中。

🌿YAML File Structure

YAML 文件应遵循特定的结构，以正确生成 API 文档，请参考以下示例：

openapi: 3.0.1
info:
  title: TSN系统前后端接口
  version: 0.1.10
servers:
  - url: /
## api描述###################################################
paths:
  /resource/net:
    post:
      tags:
        - net
      summary: 接口名称
      description: 接口描述
      ##输入参数部分，见输入参数
      responses:
        200:
          description: 查询成功
          ##输出参数部分，见输出参数

## 组件数据结构 ###############################################
components:
  schemas:
    # 网络
    basic_net_dto:
      type: object
      properties:
        net_id:
          type: string
          description: 网络ID
          example: "net-1"
        # some other properties

📌输入参数格式

## requestBody ###############################################
      ## 参数为object
      requestBody:
        description: 参数描述
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/basic_net_dto"
        required: true

      ## 参数为array
      requestBody:
        description: 参数描述
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/basic_net_dto"
        required: true


## parameters #################################################
      parameters:
        - name: 参数名称
          description: 参数描述
          in: path # or query
          required: true
          schema:
            type: 参数类型（string、number……）

📌输出参数格式

## 输出参数为 array ################################################
          content:
            application/json:
              schema:
                type: array
                description: 参数描述
                items:
                  $ref: "#/components/schemas/basic_link_dto"

## 输出参数为 object ##############################################
          content:
            application/json:
              schema:
                description: 参数描述
                $ref: "#/components/schemas/front_stream_progress_dto"

## 输出参数为 string(此处与number做区分是为了在处理格式时将enum的值作为参数名称)
          content:
            application/json:
              schema:
                type: string
                description: 参数描述
                enum: ["simulation", "reality"]
                example: "simulation"

## 输出参数为 number ##############################################
          content:
            application/json:
              schema:
                description: 参数描述
                type: number
                format: double
                example: 20.0

🌿 OutPut Array Structure

经程序处理后，输出为三个数组（用户不可见），各自的结构如下：

📌 apiList（接口列表）

apiList = [
  {
    index: number, //接口编号
    summary: string, //接口名称
    description: string, //接口描述
  },
];

📌 components（组件列表）

components = [
  {
    index: number, //组件编号
    name: string, //组件名称
    items: [
      {
        index: number, //参数编号
        name: string, //参数名称
        type: string, //参数类型
        example: string, //参数样例
        description: string, //参数描述
      },
    ],
  },
];

📌 apiDetail （接口详情）

apiDetail = [
  {
    index: number, //接口编号
    summary: string, //接口名称
    description: string, //接口描述
    path: string, //接口路径
    method: string, //接口方法
    params: [
      //输入参数
      {
        name: string, //参数名称
        type: string, //参数类型
        description: string, //参数描述
      },
    ],
    out: [
      //输出参数
      {
        name: string, //参数名称
        type: string, //参数类型
        description: string, //参数描述
      },
    ],
  },
];

🌿Customization

可以自定义传入 word 模板来控制生成文档的格式，参考文档格式如下（可见项目目录下in.docx）：

📌 接口清单

编号	名称	描述
{#apiList}{index}	{summary}	{description} {/apiList}

📌 组件定义

{#components}

表 {index} {name}定义

序号	参数名称	参数类型	参数示例	参数说明
{#items}{index}	{name}	{type}	{example}	{description}{/items}

{/components}

---

📌 接口详情

{#apiDetail}

表 {index} {summary}接口定义

接口名称	{summary}
HTTP 方法	{method}
资源路径	{path}
功能描述	{description}
输入参数	参数名称	参数类型	参数描述
	{#params}{name}	{type}	{description}{/params}
输出参数	参数名称	参数类型	参数描述
	{#out}{name}	{type}	{description}{/out}

{/apiDetail}

---

📌 more

⚡ 使用 {#api} 和 {/api} 使用 api 数组内部的参数。

⚡ word 格式可个性化定制。

🌿Output docx

编号	名称	描述
1	获取所有网络	查询系统中所有网络列表
2	创建一个新的网络	提供网络参数，创建新的网络
3	获取指定网络	根据网络 id 获取指定的网络

序号	参数名称	参数类型	参数示例	参数说明
1	net_id	string	net-1	网络 ID
2	net_name	string	分布式光伏示范网	网络名称
3	status	string	enabled	网络状态
4	nodes	array	[basic_node_dto]	节点列表
5	links	array	[basic_link_dto]	链路列表

接口名称	获取所有网络
HTTP 方法	get
资源路径	/resource/net
功能描述	查询系统中所有网络列表
输入参数	参数名称	参数类型	参数描述
输出参数	参数名称	参数类型	参数描述
	[basic_net_dto]	array	网络列表

🌿License

This project is licensed under the MIT License.