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

如何使用

方式一生成文件到本地

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

方式二生成文档到showDoc

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

例子

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

参数说明

请求参数说明

参数名	类型	必填	示例	说明
roleCode	String	-	-	-
quoteStrategyRule	QuoteStrategyRule	-	-	-
userId	int	-	-	-

返回参数说明

参数名	类型	示例	说明
code	String	"0"	状态码(非0为异常情况)
message	String	请求成功	信息描述
data	JsonResult<List<Map<InvoiceVO.Extend,InvoiceVO>>>	-	-

补充实体说明

QuoteStrategyRule

字段	类型	必填	说明	备注
id	Long	-	-	-
quoteStrategyId	Long	-	-	所属策略ID
resellerChannelId	Long	-	-	所属渠道ID
quoteStrategyCategory	Byte	-	-	所属分类 1 生活服务；2 酒店业务；3 飞机票价
type	Byte	-	-	引用ID，类型为1是0; 类型为2是大类枚举值；类型为3是子类枚举值；类型为4商品ID；类型为5是规格ID；类型为6是规格ID
name	String	-	-	类型为1是【分类名称】; 类型为2是【分类名称>大类名称】；, 类型为3是【分类名称>大类名称>子类名称】；, 类型为4是【分类名称>商品id】；类型为5是【分类名称>商品id>规格id】；, 类型为6是【分类名称>商品id>规格id>开始时间~结束时间】
refId	Long	-	-	引用ID，类型为1是0; 类型为2是大类枚举值；类型为3是子类枚举值；类型为4商品ID；类型为5是规格ID；类型为6是规格ID
startDate	Date	-	-	生效时间，类型为6时有值否则为null，格式yyyy-MM-dd HH:mm:ss
endDate	Date	-	-	失效时间，类型为6时有值否则为nu，格式yyyy-MM-dd HH:mm:ss
priceType	Byte	-	-	加价类型 1百分比 2固定金额
rate	Integer	-	-	加价百分比，当加价类型为1时，该字段有值
amount	Integer	-	-	加价金额，当加价类型为2时，该字段有值
createTime	Date	-	-	创建时间
updateTime	Date	-	-	更新时间
operator	String	-	-	操作人

InvoiceVO

字段	类型	必填	说明	备注
invoiceId	Long	-	-	-
invoiceTitleType	Byte	-	-	发票抬头类型 1：个人 2：单位
invoiceType	Byte	-	-	发票类型 1：国内纸质发票 2：国内电子发票 3:国际电子发票
name	String	-	-	个人名称
companyName	String	-	-	单位名称
status	Byte	-	-	发票状态 1：处理中 2：已开发票
taxRegisterNumber	String	-	-	纳税人识别号
invoiceCode	String	-	-	发票编号
invoiceAmount	Long	-	-	发票金额
registerAddress	String	-	-	单位注册地址
registerPhone	String	-	-	单位注册电话
bankName	String	-	-	开户银行
bankNo	String	-	-	银行卡号
contactName	String	-	-	收件人姓名
contactPhone	String	-	-	收件人手机号
contactAddress	String	-	-	收件人地址
contactEmail	String	-	-	收件人邮箱
expressNo	String	-	-	快递单号
expressName	String	-	-	快递公司
fileUrl	String	-	-	发票电子文件地址
filePath	String	-	-	发票电子文件地址
supplierId	Integer	-	-	实际供应商id
ownerId	Integer	-	-	ownerId
userId	Integer	-	-	userId
remark	String	-	-	备注
yn	Boolean	-	-	删除标识
createTime	Date	-	-	创建时间
updateTime	Date	-	-	更新时间
createPin	String	-	-	创建人
updatePin	String	-	-	更新人
invoiceNo	Long	-	-	发票编号-子
invoiceTitle	String	-	-	发票标题-子
invoiceEnum	InvoiceEnum	-	-	发票类型-子
extendSub	ExtendSub	-	-	扩展信息

JsonResult

字段	类型	必填	说明	备注
code	Integer	-	-	code 为"0"则无异常
msg	String	-	-	msg
data	T	-	-	data 返回体对象

Extend

字段	类型	必填	说明	备注
title	String	-	-	标题-父
content	String	-	-	内容-父

InvoiceEnum

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

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

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

ExtendSub

字段	类型	必填	说明	备注
title	String	-	-	标题-父
content	String	-	-	内容-父
spuList	List<Spu>	-	-	spu集合-子
spu	Spu	-	-	spu信息-子
spuMap	Map<String,Spu>	-	-	spu Map-子
specialChannelEnum	SpecialChannelEnum	-	-	渠道枚举

Spu

字段	类型	必填	说明	备注
id	long	-	-	主键ID
productType	byte	-	-	商品类别
productSubType	int	-	-	商品子类别
nameCn	String	-	-	spu中文名称
nameEn	String	-	-	spu英文名称
poiIds	String	-	-	poiId，按照poi_id顺序逗号分隔，eg：1,3,12
name	String	-	-	业务字段 , 多语言处理后显示的name，v1.5.1新增
createPin	String	-	-	创建人
updatePin	String	-	-	更新人
keyList	List<Key>	-	-	key集合

SpecialChannelEnum

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

Key

字段	类型	必填	说明	备注
pageSize	Integer	-	-	-
type	byte	-	-	要素类别
name	String	-	-	要素名称
names	Map<String,String>	-	-	业务字段 , 要素名称多语言map, Map<languageCode, value>
keyList	List<Key>	-	-	-

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
README.md		README.md
main.py		main.py
param.txt		param.txt
request_show_doc.py		request_show_doc.py

lurenha/ApiFormatMd

Folders and files

Latest commit

History

Repository files navigation

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

特点

配置项

main.py

param.txt

依赖

如何使用

方式一生成文件到本地

方式二生成文档到showDoc

例子

java接口

QuoteStrategyRule(参数)

InvoiceVO(返回主体)

Invoice (InvoiceVO父类)

Spu(InvoiceVO.ExtendSub 依赖)

Key (Spu,Key 依赖)

生成内容

接口说明

HTTP请求地址

请求方式

参数说明

请求参数说明

返回参数说明

补充实体说明

QuoteStrategyRule

InvoiceVO

JsonResult

Extend

InvoiceEnum

ExtendSub

Spu

SpecialChannelEnum

Key

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages