ApiFormatMd 轻量级Java接口文档生成工具

特点

• 完全基于本地代码执行 Java代码无需引用额外依赖
• 生成MarkDown格式文档 可使用ShowDoc生成在线文档

配置项

main.py

• 作者 author = ‘江火似流萤’ (对应Md文档作者信息)
• 载入类根目录 root_path = r"/Users/xxx" (指定Java项目根目录,程序以此为起点遍历Java文件)
• 生成md文件目录 write_path = r"/Users/xxx/Desktop" (Md文档写入路径)

param.txt

• 参数 param.txt (Controller层接口信息 具体参考文件内容)

依赖

• python3

如何使用

方式一 生成文件到本地

1. 本地安装python3环境
2. clone本项目到本地
3. 修改main.py ‘author’ ‘root_path’ 'write_path’配置(首次使用配置)
4. API信息写入 param.txt 文件
5. 执行 python3 main.py终端输出 ‘success’ 则执行成功

方式二 生成文档到showDoc

1. 基于方式一的配置 执行 python3 request_show_doc.py
2. 打开 https://www.showdoc.com.cn/2040347871634336/ 查看文档
3. 如果报错ModuleNotFoundError: No module named 'requests'需要导入request包执行 pip3 install requests

方式三 写入utools插件一键生成文档到showDoc

1. utools 安装一步到位插件
2. 创建自己的插件
3. 复制接口到utools生成文档

• 复制接口
  
• 粘贴到utools
• 成功提示(文档地址已复制到粘贴板)
• 浏览器打开文档
  

点击gitee查看源码

例子

java接口

    @RequestMapping(value = "/v1/test/{userId}", method = RequestMethod.POST)
    public JsonResult<List<Map<InvoiceVO.Extend, InvoiceVO>>> test(
            @PathVariable(value = "userId") int userId,
            @RequestParam(value = "roleCode", required = true) String roleCode,
            @RequestBody QuoteStrategyRule quoteStrategyRule) {
        return new JsonResult<>();
    }

QuoteStrategyRule(参数)

package com.peng.model;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.util.Date;

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@TableName("quote_strategy_rule")
public class QuoteStrategyRule implements Serializable {
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    /**
     * 所属策略ID
     */
    private Long quoteStrategyId;

    /**
     * 所属渠道ID
     */
    private Long resellerChannelId;

    /**
     * 所属分类 1 生活服务；2 酒店业务；3 飞机票价
     */
    private Byte quoteStrategyCategory;

    /**
     * 引用ID，类型为1是0; 类型为2是大类枚举值； 类型为3是子类枚举值；类型为4商品ID；类型为5是规格ID；类型为6是规格ID
     */
    private Byte type;

    /**
     * 类型为1是【分类名称】; 类型为2是【分类名称>大类名称】；
     * 类型为3是【分类名称>大类名称>子类名称】；
     * 类型为4是【分类名称>商品id】；类型为5是【分类名称>商品id>规格id】；
     * 类型为6是【分类名称>商品id>规格id>开始时间~结束时间】
     */
    private String name;

    /**
     * 引用ID，类型为1是0; 类型为2是大类枚举值； 类型为3是子类枚举值；类型为4商品ID；类型为5是规格ID；类型为6是规格ID
     */
    private Long refId;

    /**
     * 生效时间，类型为6时有值否则为null，格式yyyy-MM-dd HH:mm:ss
     */
    private Date startDate;

    /**
     * 失效时间，类型为6时有值否则为nu，格式yyyy-MM-dd HH:mm:ss
     */
    private Date endDate;

    /**
     * 加价类型 1百分比 2固定金额
     */
    private Byte priceType;

    /**
     * 加价百分比，当加价类型为1时，该字段有值
     */
    private Integer rate;

    /**
     * 加价金额，当加价类型为2时，该字段有值
     */
    private Integer amount;

    /**
     * 创建时间
     */
    private Date createTime;

    /**
     * 更新时间
     */
    private Date updateTime;

    /**
     * 操作人
     */
    private String operator;
}

InvoiceVO(返回主体)

@Data
public class InvoiceVO extends Invoice {

    //发票编号-子
    private Long invoiceNo;
    //发票标题-子
    private String invoiceTitle;

    /**
     * 发票类型-子
     */
    private InvoiceEnum invoiceEnum;

    //扩展信息
    private ExtendSub extendSub;

    @Data
    public static class Extend {
        //标题-父
        private String title;
        //内容-父
        private String content;

    }

    @Data
    public static class ExtendSub extends Extend {
        //spu集合-子
        private List<Spu> spuList;
        //spu信息-子
        private Spu spu;

        /**
         *  spu Map-子
         */

        private Map<String, Spu> spuMap;

        //渠道枚举
        private SpecialChannelEnum specialChannelEnum;

    }
}

Invoice (InvoiceVO父类)

package com.peng.model;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.util.Date;

@JsonInclude(value = JsonInclude.Include.NON_NULL)//为NULL的字段不返回为（JSON）
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@TableName("trade_invoice")
public class Invoice implements Serializable {

    @TableId(value = "invoice_id", type = IdType.AUTO)
    private Long invoiceId;
    /**
     * 发票抬头类型 1：个人 2：单位
     */
    private Byte invoiceTitleType;

    /**
     * 发票类型 1：国内纸质发票 2：国内电子发票 3:国际电子发票
     */
    private Byte invoiceType;

    /**
     * 个人名称
     */
    private String name;

    /**
     * 单位名称
     */
    private String companyName;

    /**
     * 发票状态 1：处理中 2：已开发票
     */
    private Byte status;

    /**
     * 纳税人识别号
     */
    private String taxRegisterNumber;

    /**
     * 发票编号
     */
    private String invoiceCode;

    /**
     * 发票金额
     */
    private Long invoiceAmount;

    /**
     * 单位注册地址
     */
    private String registerAddress;

    /**
     * 单位注册电话
     */
    private String registerPhone;

    /**
     * 开户银行
     */
    private String bankName;

    /**
     * 银行卡号
     */
    private String bankNo;

    /**
     * 收件人姓名
     */
    private String contactName;

    /**
     * 收件人手机号
     */
    private String contactPhone;

    /**
     * 收件人地址
     */
    private String contactAddress;

    /**
     * 收件人邮箱
     */
    private String contactEmail;

    /**
     * 快递单号
     */
    private String expressNo;

    /**
     * 快递公司
     */
    private String expressName;

    /**
     * 发票电子文件地址
     */
    private String fileUrl;

    /**
     * 发票电子文件地址
     */
    private String filePath;

    /**
     * 实际供应商id
     */
    private Integer supplierId;

    /**
     * ownerId
     */
    private Integer ownerId;

    /**
     * userId
     */
    private Integer userId;

    /**
     * 备注
     */
    private String remark;

    /**
     * 删除标识
     */
    private Boolean yn;

    /**
     * 创建时间
     */
    private Date createTime;

    /**
     * 更新时间
     */
    private Date updateTime;

    /**
     * 创建人
     */
    private String createPin;

    /**
     * 更新人
     */
    private String updatePin;

}

Spu(InvoiceVO.ExtendSub 依赖)

@Data
public class Spu implements Serializable {
    private static final long serialVersionUID = 128833531741299945L;
    /**
     * 主键ID
     */
    private long id;

    /**
     * 商品类别
     */
    private byte productType;

    /**
     * 商品子类别
     */
    private int productSubType;

    /**
     * spu中文名称
     */
    private String nameCn;

    /**
     * spu英文名称
     */
    private String nameEn;

    /**
     * poiId，按照poi_id顺序逗号分隔，eg：1,3,12
     */
    private String poiIds;

    /****** 业务字段 ********/

    /**
     * 多语言处理后显示的name，v1.5.1新增
     */
    private String name;

    /**
     * 创建人
     */
    private String createPin;


    /**
     * 更新人
     */

    private String updatePin;

    //key集合
    private List<Key> keyList;

}

Key (Spu,Key 依赖)

@Data
public class Key implements Serializable {
    private static final long serialVersionUID = 7585869752216827433L;
    private Integer pageSize;
    /**
     * 要素类别
     */
    private byte type;

    /**
     * 要素名称
     */
    private String name;

    /****** 业务字段 *******/
    /**
     * 要素名称多语言map
     * Map<languageCode, value>
     */
    private Map<String, String> names;

    private List<Key> keyList;
}

生成内容

接口说明

HTTP请求地址

• 地址: http://domain//v1/test/{userId}

请求方式

• POST

参数说明

请求参数说明

返回参数说明

补充实体说明

QuoteStrategyRule

InvoiceVO

JsonResult

Extend

InvoiceEnum

enum InvoiceEnum {
    PERSON(1, "抬头为个人"),
    COMPANY(2, "抬头为单位"),

    BEING(1, "发票状态处理中"),
    COMPLETE(2, "发票状态已完成"),

    PAPER(1, "纸质发票"),
    ELECTRONIC(2, "电子发票");

ExtendSub

Spu

SpecialChannelEnum

enum SpecialChannelEnum implements CommonEnum{
    DEFAULT("DEFAULT", "默认渠道"),
    SASS("SASS", "SASS平台"),
    UNKNOWN("UNKNOWN", "UNKNOWN"),
    ;

Key