Regular + Python: a lightweight interface documentation tool

ApiFormatMd lightweight Java interface document generation tool

characteristic

  • Execute Java code completely based on native code without reference to additional dependencies
  • Generate MarkDown format documents. You can use ShowDoc to generate online documents

Configuration item

main.py

  • Author = 'River fire is like a firefly' (corresponding to the author information of Md document)
  • Load the class root directory root_path = r"/Users/xxx" (specify the root directory of the Java project, and the program uses this as the starting point to traverse the java files)
  • Generate md file directory write_path = r"/Users/xxx/Desktop" (Md document write path)

param.txt

  • Parameter param Txt (refer to the contents of the file for details of the controller layer interface information)

rely on

  • python3

How to use

Method 1: generate files locally

  1. Install Python 3 environment locally
  2. clone the project to the local
  3. Modify main py ‘author’ ‘root_path’ 'write_path 'configuration (first use configuration)
  4. API information is written into param Txt file
  5. Execute Python 3 main If the PY terminal outputs' success', the execution is successful

Method 2: generate documents to showDoc

  1. Execute python3 request based on the configuration of mode 1_ show_ doc.py
  2. Open https://www.showdoc.com.cn/2040347871634336/ View document
  3. If an error is reported, ModuleNotFoundError: No module named 'requests', you need to import the request package and execute pip3 install requests

Method 3: write the utools plug-in to generate a document to showDoc with one click

  1. utools installs one-step plug-ins
  2. Create your own plug-in
  3. Copy the interface to utools to generate documents
  • Copy interface
  • Paste to utools
  • Success prompt (the document address has been copied to the pasteboard)
  • Browser open document

Click gitee to view the source code

example

java interface

view code
    @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 (parameter)
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;

    /**
     * Policy ID
     */
    private Long quoteStrategyId;

    /**
     * Channel ID
     */
    private Long resellerChannelId;

    /**
     * Category 1: life service; 2 hotel business; (3) air fare
     */
    private Byte quoteStrategyCategory;

    /**
     * Reference ID, type 1 is 0; Type 2 is a large class enumeration value; Type 3 is a subclass enumeration value; Commodity ID of type 4; Type 5 is the specification ID; Type 6 is the specification ID
     */
    private Byte type;

    /**
     * Type 1 is classification name; Type 2 is [category name > category name];
     * Type 3 is [classification name > category name > sub category name];
     * Type 4 is [classification name > commodity id]; Type 5 is [classification name > commodity id > specification id];
     * Type 6 is [classification name > commodity ID > specification ID > start time ~ end time]
     */
    private String name;

    /**
     * Reference ID, type 1 is 0; Type 2 is a large class enumeration value; Type 3 is a subclass enumeration value; Commodity ID of type 4; Type 5 is the specification ID; Type 6 is the specification ID
     */
    private Long refId;

    /**
     * Effective time: when the type is 6, it has a value; otherwise, it is null. The format is yyyy MM DD HH: mm: SS
     */
    private Date startDate;

    /**
     * Expiration time: if the type is 6, it has a value; otherwise, it is nu. The format is yyyy MM DD HH: mm: SS
     */
    private Date endDate;

    /**
     * Mark up type 1 percentage 2 fixed amount
     */
    private Byte priceType;

    /**
     * Markup percentage. When the markup type is 1, this field has a value
     */
    private Integer rate;

    /**
     * Markup amount: when the markup type is 2, this field has a value
     */
    private Integer amount;

    /**
     * Creation time:
     */
    private Date createTime;

    /**
     * Update time:
     */
    private Date updateTime;

    /**
     * Operator
     */
    private String operator;
}

Invoicevo (return principal)
@Data
public class InvoiceVO extends Invoice {

    //Invoice No. - sub
    private Long invoiceNo;
    //Invoice title - sub
    private String invoiceTitle;

    /**
     * Invoice type - sub
     */
    private InvoiceEnum invoiceEnum;

    //Extended information
    private ExtendSub extendSub;

    @Data
    public static class Extend {
        //Title - parent
        private String title;
        //Content - parent
        private String content;

    }

    @Data
    public static class ExtendSub extends Extend {
        //spu set - sub
        private List<Spu> spuList;
        //spu information - sub
        private Spu spu;

        /**
         *  spu Map-son
         */

        private Map<String, Spu> spuMap;

        //Channel enumeration
        private SpecialChannelEnum specialChannelEnum;

    }
}
Invoice (InvoiceVO parent class)
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)//Fields that are NULL are not returned as (JSON)
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@TableName("trade_invoice")
public class Invoice implements Serializable {

    @TableId(value = "invoice_id", type = IdType.AUTO)
    private Long invoiceId;
    /**
     * Invoice header type 1: individual 2: Company
     */
    private Byte invoiceTitleType;

    /**
     * Invoice type 1: domestic paper invoice 2: domestic electronic invoice 3: international electronic invoice
     */
    private Byte invoiceType;

    /**
     * Personal name:
     */
    private String name;

    /**
     * Unit name:
     */
    private String companyName;

    /**
     * Invoice status 1: in process 2: invoiced
     */
    private Byte status;

    /**
     * Taxpayer identification number
     */
    private String taxRegisterNumber;

    /**
     * Invoice No.:
     */
    private String invoiceCode;

    /**
     * Invoice amount
     */
    private Long invoiceAmount;

    /**
     * Registered address:
     */
    private String registerAddress;

    /**
     * Company registration telephone:
     */
    private String registerPhone;

    /**
     * Bank of deposit
     */
    private String bankName;

    /**
     * Bank card number
     */
    private String bankNo;

    /**
     * Recipient name:
     */
    private String contactName;

    /**
     * Recipient's mobile number
     */
    private String contactPhone;

    /**
     * Addressee address:
     */
    private String contactAddress;

    /**
     * Recipient mailbox
     */
    private String contactEmail;

    /**
     * courier number
     */
    private String expressNo;

    /**
     * Courier Services Company
     */
    private String expressName;

    /**
     * Invoice electronic file address
     */
    private String fileUrl;

    /**
     * Invoice electronic file address
     */
    private String filePath;

    /**
     * Actual supplier id
     */
    private Integer supplierId;

    /**
     * ownerId
     */
    private Integer ownerId;

    /**
     * userId
     */
    private Integer userId;

    /**
     * remarks
     */
    private String remark;

    /**
     * Delete identity
     */
    private Boolean yn;

    /**
     * Creation time:
     */
    private Date createTime;

    /**
     * Update time:
     */
    private Date updateTime;

    /**
     * Created by:
     */
    private String createPin;

    /**
     * Updated by:
     */
    private String updatePin;

}

Spu(InvoiceVO.ExtendSub dependency)
@Data
public class Spu implements Serializable {
    private static final long serialVersionUID = 128833531741299945L;
    /**
     * Primary key ID
     */
    private long id;

    /**
     * Commodity category
     */
    private byte productType;

    /**
     * Commodity subcategory
     */
    private int productSubType;

    /**
     * spu Chinese Name:
     */
    private String nameCn;

    /**
     * spu English name
     */
    private String nameEn;

    /**
     * poiId´╝îAccording to poi_id order comma separated, eg: 1,3,12
     */
    private String poiIds;

    /****** Business field********/

    /**
     * name displayed after multilingual processing, added in v1.5.1
     */
    private String name;

    /**
     * Created by:
     */
    private String createPin;


    /**
     * Updated by:
     */

    private String updatePin;

    //"key": "collection"
    private List<Key> keyList;

}
Key (Spu,Key dependent)
@Data
public class Key implements Serializable {
    private static final long serialVersionUID = 7585869752216827433L;
    private Integer pageSize;
    /**
     * Element category
     */
    private byte type;

    /**
     * Element name
     */
    private String name;

    /****** Business field*******/
    /**
     * Feature name multilingual map
     * Map<languageCode, value>
     */
    private Map<String, String> names;

    private List<Key> keyList;
}

Generate content

View content

Interface description

namedescribe
functionI can't find my name. Use this
person in chargeThe river is like a firefly

HTTP request address

  • Address: http://domain//v1/test/{userId}

Request mode:

  • POST

Parameter description

Request parameter description

Parameter nametypeRequiredExample:explain
roleCodeString---
quoteStrategyRuleQuoteStrategyRule---
userIdint---

Return parameter description

Parameter nametypeExample:explain
codeString"0"Status code (non-0 is abnormal)
messageStringRequest succeededInformation description
dataJsonResult<List<Map<InvoiceVO.Extend,InvoiceVO>>>--

Supplementary entity description

QuoteStrategyRule
fieldtypeRequiredexplainremarks
idLong---
quoteStrategyIdLong--Policy ID
resellerChannelIdLong--Channel ID
quoteStrategyCategoryByte--Category 1: life service; 2 hotel business; (3) air fare
typeByte--Reference ID, type 1 is 0; Type 2 is a large class enumeration value; Type 3 is a subclass enumeration value; Commodity ID of type 4; Type 5 is the specification ID; Type 6 is the specification ID
nameString--Type 1 is classification name; Type 2 is [category name > category name];, Type 3 is [classification name > category name > sub category name];, Type 4 is [classification name > commodity id]; Type 5 is [classification name > commodity id > specification id];, Type 6 is [classification name > commodity id > specification id > start time ~ end time]
refIdLong--Reference ID, type 1 is 0; Type 2 is a large class enumeration value; Type 3 is a subclass enumeration value; Commodity ID of type 4; Type 5 is the specification ID; Type 6 is the specification ID
startDateDate--Effective time: when the type is 6, it has a value; otherwise, it is null. The format is yyyy MM DD HH: mm: SS
endDateDate--Expiration time: if the type is 6, it has a value; otherwise, it is nu. The format is yyyy MM DD HH: mm: SS
priceTypeByte--Mark up type 1 percentage 2 fixed amount
rateInteger--Markup percentage. When the markup type is 1, this field has a value
amountInteger--Markup amount: when the markup type is 2, this field has a value
createTimeDate--Creation time:
updateTimeDate--Update time:
operatorString--Operator
InvoiceVO
fieldtypeRequiredexplainremarks
invoiceIdLong---
invoiceTitleTypeByte--Invoice header type 1: individual 2: Company
invoiceTypeByte--Invoice type 1: domestic paper invoice 2: domestic electronic invoice 3: international electronic invoice
nameString--Personal name:
companyNameString--Unit name:
statusByte--Invoice status 1: in process 2: invoiced
taxRegisterNumberString--Taxpayer identification number
invoiceCodeString--Invoice No.:
invoiceAmountLong--Invoice amount
registerAddressString--Registered address:
registerPhoneString--Company registration telephone:
bankNameString--Bank of deposit
bankNoString--Bank card number
contactNameString--Recipient name:
contactPhoneString--Recipient's mobile number
contactAddressString--Addressee address:
contactEmailString--Recipient mailbox
expressNoString--courier number
expressNameString--Courier Services Company
fileUrlString--Invoice electronic file address
filePathString--Invoice electronic file address
supplierIdInteger--Actual supplier id
ownerIdInteger--ownerId
userIdInteger--userId
remarkString--remarks
ynBoolean--Delete identity
createTimeDate--Creation time:
updateTimeDate--Update time:
createPinString--Created by:
updatePinString--Updated by:
invoiceNoLong--Invoice No. - sub
invoiceTitleString--Invoice title - sub
invoiceEnumInvoiceEnum--Invoice type - sub
extendSubExtendSub--Extended information
JsonResult
fieldtypeRequiredexplainremarks
codeInteger--No exception if code is "0"
msgString--msg
dataT--data return body object
Extend
fieldtypeRequiredexplainremarks
titleString--Title - parent
contentString--Content - parent
InvoiceEnum
enum InvoiceEnum {
    PERSON(1, "Head to individual"),
    COMPANY(2, "Header is the unit"),

    BEING(1, "Invoice status processing"),
    COMPLETE(2, "Invoice status completed"),

    PAPER(1, "Paper invoice"),
    ELECTRONIC(2, "Electronic invoice");
ExtendSub
fieldtypeRequiredexplainremarks
titleString--Title - parent
contentString--Content - parent
spuListList<Spu>--spu set - sub
spuSpu--spu information - sub
spuMapMap<String,Spu>--spu Map sub
specialChannelEnumSpecialChannelEnum--Channel enumeration
Spu
fieldtypeRequiredexplainremarks
idlong--Primary key ID
productTypebyte--Commodity category
productSubTypeint--Commodity subcategory
nameCnString--spu Chinese name
nameEnString--spu English name
poiIdsString--poiId, according to poi_id order comma separated, eg: 1,3,12
nameString--Business field, name displayed after multilingual processing, added in v1.5.1
createPinString--Created by:
updatePinString--Updated by:
keyListList<Key>--"key": "collection"
SpecialChannelEnum
enum SpecialChannelEnum implements CommonEnum{
    DEFAULT("DEFAULT", "Default channel"),
    SASS("SASS", "SASS platform"),
    UNKNOWN("UNKNOWN", "UNKNOWN"),
    ;
Key
fieldtypeRequiredexplainremarks
pageSizeInteger---
typebyte--Element category
nameString--Element name
namesMap<String,String>--Business field, element name multilingual map, map < languagecode, value >
keyListList<Key>---

Tags: Python Java programming language

Posted by maseeha on Wed, 24 Aug 2022 07:29:09 +0300