yaml-api-doc v1.0.7

API Documentation Generator

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

:herb:Installation

yarn add yaml-api-doc

或

npm install yaml-api-doc

:herb: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 中。

:herb: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

:pushpin:输入参数格式

## 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……）

:pushpin:输出参数格式

## 输出参数为 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

:herb: OutPut Array Structure

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

:pushpin: apiList（接口列表）

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

:pushpin: components（组件列表）

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

:pushpin: 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, //参数描述
      },
    ],
  },
];

:herb:Customization

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

:pushpin: 接口清单

:pushpin: 组件定义

{#components}

表 {index} {name}定义

{/components}

:pushpin: 接口详情

{#apiDetail}

表 {index} {summary}接口定义

{/apiDetail}

:pushpin: more

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

:zap: word 格式可个性化定制。

:herb:Output docx

:herb:License

This project is licensed under the MIT License.