Eolink 神技之一:基于数据库智能生成 API 文档

Eolink 神技之二:API 全生命周期治理

Eolink 神技之三:钉钉、企业微信、蓝信、飞书等工具API对接


前言

咱们在开发过程中会有很多小伙伴一起来做合作开发,然而会呈现一个问题,就是每个人的正文习惯都不雷同,那么,咱们在后续理解程序的时候就很麻烦,Eolink 提供的这个性能就十分棒,能够间接主动全代码正文,咱们只须要填写大量的关键字即可。十分的不便高效,并且对立了正文标准。在本博客中,我会先演示主动全代码正文,之后会依据咱们正文的内容一键式上传到咱们的 Eolink 进行批量测试。


一、主动全代码正文

Eolink 提供了【idea】的【Eolink ApiKit】插件,此插件能够疾速的将类与函数均增加一个规范的 Eolink 正文办法。

正文示例:

这里为了测试不便,我写了一些间接返回的测试接口。

1/**2 * @eo.name UpdateById3 * @eo.url /api/UpdateById4 * @eo.method put5 * @eo.request-type formdata6 * @param id7 * @param introduce8 * @return Object9 */@PutMapping("/api/UpdateById")public Object UpdateById(String id,String introduce) {10   try {11       return new SUCCESS("批改"+id+"胜利", UUID.randomUUID());12   } catch (Exception e) {13       return new ERROR("批改"+id+"失败", UUID.randomUUID());14   }15}


1、测试环境

测试语言:Java

零碎环境:win10

开发环境:IntelliJ IDEA 2021.3.2(反对 2020-2022 年版本)

Plugins 搜寻:【Eolink Apikit】点击【install】装置。


2、Eolink Apikit 装置

2.1 自建 bootstrap 我的项目用作测试

这块步骤就略过了,咱们程序员应该都是会的。我用的 maven 的 pom.xml 我分享一下。一看就晓得是个自定义的返回测试微服务。

1    <dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-tomcat</artifactId><scope>provided</scope></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies>

2.2 操作地位

点击【File】->【Settings...】



2.3 搜寻并装置【Eolink ApiKit】

这里须要依照步骤操作:

  1. 抉择【Plugins】。
  2. 在搜寻框中搜寻【Eolink ApiKit】。
  3. 点击搜寻后果【Search Results】中呈现的【Eolink ApiKit】的【Install】按钮,我这里装置过了,故而显示一个过来时的【Installed】。
  4. 点击【OK】确认操作。



2.4 增加 eo 正文

这里我给了个示例代码,不便操作,这也是未加正文的类与函数。

1 import org.springframework.web.bind.annotation.*;2 3 import java.util.UUID;4 5 @RestController@CrossOriginpublic class EolinkApiController {6 7     @GetMapping("/api/GetInfo")public Object GetInfo() {8         return new SUCCESS("初始化胜利", UUID.randomUUID());9     }10 11    @GetMapping("/api/SelectById")public Object SelectById(String id) {12        return new SUCCESS("查问"+id+"胜利", UUID.randomUUID());13    }14 15    @PostMapping("/api/Login")public Object Login(String userName,String passWord) {16        return new SUCCESS("登录胜利", UUID.randomUUID());17    }1819    @PostMapping("/api/AddInfo")public Object AddInfo(String userName,String passWord,String introduce) {20        return new SUCCESS("增加胜利", UUID.randomUUID());21    }2223    @PutMapping("/api/UpdateById")public Object UpdateById(String id,String introduce) {24        try {25            return new SUCCESS("批改"+id+"胜利", UUID.randomUUID());26        } catch (Exception e) {27            return new ERROR("批改"+id+"失败", UUID.randomUUID());28        }29    }30 }31 //本人找个地位创立一个,这个不须要引入到API中,我就不便用于返回class BackResult {32     public BackResult(String message, Object result) {33         this.state = true;34         this.message = message;35         this.result = result;36     }37 38     public boolean state;39     public String message;40     public Object result;41 }42 43 class SUCCESS extends BackResult {44 45     public SUCCESS(String message, Object result) {46         super(message, result);47         this.state = true;48     }49 }5051 class ERROR extends BackResult {5253     public ERROR(String message, Object result) {54         super(message, result);55         this.state = false;56     }57 }

增加正文办法:

鼠标右键点击【Generate Class Doc】抉择【HTTP】即可引入



2.5 正文成果

1 import org.springframework.web.bind.annotation. ;  2 3 import java.util.UUID;  4 5 /*6  * @eo.api-type http7  * @eo.groupName 默认分组8  * @eo.path9  /@RestController@CrossOriginpublic class EolinkApiController {  10 11    /*12     * @eo.name GetInfo13     * @eo.url /api/GetInfo14     * @eo.method get15     * @eo.request-type formdata16     * @return Object17     /@GetMapping("/api/GetInfo")public Object GetInfo() { 18        return new SUCCESS("初始化胜利", UUID.randomUUID()); 19    }  20 21    /*22     * @eo.name SelectById23     * @eo.url /api/SelectById24     * @eo.method get25     * @eo.request-type formdata26     * @param id27     * @return Object28     /@GetMapping("/api/SelectById")public Object SelectById(String id) { 29        return new SUCCESS("查问"+id+"胜利", UUID.randomUUID()); 30    }  31 32    /*33     * @eo.name Login34     * @eo.url /api/Login35     * @eo.method post36     * @eo.request-type formdata37     * @param userName38     * @param passWord39     * @return Object40     /@PostMapping("/api/Login")public Object Login(String userName,String passWord) { 41        return new SUCCESS("登录胜利", UUID.randomUUID()); 42    }  43 44    /*45     * @eo.name AddInfo46     * @eo.url /api/AddInfo47     * @eo.method post48     * @eo.request-type formdata49     * @param userName50     * @param passWord51     * @param introduce52     * @return Object53     /@PostMapping("/api/AddInfo")public Object AddInfo(String userName,String passWord,String introduce) { 54        return new SUCCESS("增加胜利", UUID.randomUUID()); 55    }5657    /*58     * @eo.name UpdateById59     * @eo.url /api/UpdateById60     * @eo.method put61     * @eo.request-type formdata62     * @param id63     * @param introduce64     * @return Object65     */@PutMapping("/api/UpdateById")public Object UpdateById(String id,String introduce) {66        try {67            return new SUCCESS("批改"+id+"胜利", UUID.randomUUID());68        } catch (Exception e) {69            return new ERROR("批改"+id+"失败", UUID.randomUUID());70        }71    }72 }


二、一键上传API

1、配置服务信息

前置条件:再次关上【Settings】

操作步骤:

  1. 搜寻 Eolink
  2. 抉择 Eolink Settings
  3. 服务器上获取【Server】、【SpaceKey】、【ProjectHashKey】
  4. 输出注册账号
  5. StringType 抉择【camelCase(default)】
  6. 点击【OK】,这里为了能放大的截图我就没截取【OK】,间接能看到的。


2、Server获取

在本人的网页服务中就能看到对应的域名,然而这里在域名前面须要加上【/api】


3、SpaceKey 获取

大胆的往后拉,网址的最初一个参数就是咱们要的 spaceKey。


4、ProjectHashKey获取

复制的时候认真一些,别落下一个两个字符的。


5、抉择上传分组

因为主动正文会抉择【默认分组】,咱们须要把默认分组改一下。

增加分组

我创立了一个叫做【Eolink20221124】 的分组。

查看未上传的组。

批改正文


6、一键上传 API ——单个 API 上传

鼠标右键抉择【Upload Api】就是单个 API 上传。

先抉择须要上传的 API 接口名称,再点击 Upload 上传即可。

右下角会显示上传胜利提醒,这里仅仅上传了【GetInfo】所以只显示一个。

胜利成果:


2.7、一键上传 API ——上传所有 API

抉择【Upload All Api】

上传胜利显示,这里显示了上传了所有的 API。

胜利成果:


8、接口测试

测试胜利:


三、接口正文

我写了个接口类,能够间接复制过来测试一下,很不便。

1 public interface EolinkDAO {2     public Object GetInfo();3     public Object SelectById(String id) ;4     public Object Login(String userName,String passWord);5     public Object AddInfo(String userName,String passWord,String introduce);6     public Object UpdateById(String id,String introduce);7 }

这是正文成果:

1 /**2  * @eo.api-type http3  * @eo.groupName 默认分组4  * @eo.path5  /public interface EolinkDAO { 6     /*7      * @eo.name GetInfo8      * @eo.url9      * @eo.method get10     * @eo.request-type formdata11     * @return Object12     /public Object GetInfo(); 13    /*14     * @eo.name SelectById15     * @eo.url16     * @eo.method get17     * @eo.request-type formdata18     * @param id19     * @return Object20     /public Object SelectById(String id) ; 21    /*22     * @eo.name Login23     * @eo.url24     * @eo.method get25     * @eo.request-type formdata26     * @param userName27     * @param passWord28     * @return Object29     /public Object Login(String userName,String passWord); 30    /*31     * @eo.name AddInfo32     * @eo.url33     * @eo.method get34     * @eo.request-type formdata35     * @param userName36     * @param passWord37     * @param introduce38     * @return Object39     /public Object AddInfo(String userName,String passWord,String introduce); 40    /*41     * @eo.name UpdateById42     * @eo.url43     * @eo.method get44     * @eo.request-type formdata45     * @param id46     * @param introduce47     * @return Object48     */public Object UpdateById(String id,String introduce);49 }


四、属性正文

测试代码:

1 import java.util.Date;2 3 public class Eolink {4     private String id;5     private Date createDate;6     private String projectName;7     private String introduce;8 9     public String getId() {10        return id;11    }1213    public void setId(String id) {14        this.id = id;15    }1617    public Date getCreateDate() {18        return createDate;19    }2021    public void setCreateDate(Date createDate) {22        this.createDate = createDate;23    }2425    public String getProjectName() {26        return projectName;27    }2829    public void setProjectName(String projectName) {30        this.projectName = projectName;31    }3233    public String getIntroduce() {34        return introduce;35    }3637    public void setIntroduce(String introduce) {38        this.introduce = introduce;39    }40 }

正文成果:

1 import java.util.Date;2 3 /**4  * @eo.api-type http5  * @eo.groupName 默认分组6  * @eo.path7  /public class Eolink { 8     private String id; 9     private Date createDate; 10    private String projectName; 11    private String introduce;  12 13    /*14     * @eo.name getId15     * @eo.url16     * @eo.method get17     * @eo.request-type formdata18     * @return String19     /public String getId() { 20        return id; 21    }  2223    /*24     * @eo.name setId25     * @eo.url26     * @eo.method get27     * @eo.request-type formdata28     * @param id29     * @return void30     /public void setId(String id) { 31        this.id = id; 32    }  3334    /*35     * @eo.name getCreateDate36     * @eo.url37     * @eo.method get38     * @eo.request-type formdata39     * @return Date40     /public Date getCreateDate() { 41        return createDate; 42    }  4344    /*45     * @eo.name setCreateDate46     * @eo.url47     * @eo.method get48     * @eo.request-type formdata49     * @param createDate50     * @return void51     /public void setCreateDate(Date createDate) { 52        this.createDate = createDate; 53    }  5455    /*56     * @eo.name getProjectName57     * @eo.url58     * @eo.method get59     * @eo.request-type formdata60     * @return String61     /public String getProjectName() { 62        return projectName; 63    }  64   65    /*66     * @eo.name setProjectName67     * @eo.url68     * @eo.method get69     * @eo.request-type formdata70     * @param projectName71     * @return void72     /public void setProjectName(String projectName) { 73        this.projectName = projectName; 74    }  75  76    /*77     * @eo.name getIntroduce78     * @eo.url79     * @eo.method get80     * @eo.request-type formdata81     * @return String82     /public String getIntroduce() { 83        return introduce; 84    }  85   86    /*87     * @eo.name setIntroduce88     * @eo.url89     * @eo.method get90     * @eo.request-type formdata91     * @param introduce92     * @return void93     */public void setIntroduce(String introduce) {94        this.introduce = introduce;95    }


五、总结

主动正文我测试了类和函数、属性等内容,都是能够正文的,而且很规范的正文,咱们在方才的整个操作过程中也能看到其规范度还是很高的。

这是根底的一个类的 main 办法正文。甚至只有有肯定英语根底的小朋友也能很明确的看出正文的信息,所以十分的举荐给刚上大学的小朋友们,当前再也不会被老师说没写正文,或者正文写的不规范了,并且所有接口都能一键上传, 测试起来也是很不便。

1 /**2  * @eo.api-type http3  * @eo.groupName 默认分组4  * @eo.path5  /public class Action { 6     /*7      * @eo.name main8      * @eo.url9      * @eo.method get10     * @eo.request-type formdata11     * @param args12     * @return void13     */public static void main(String[] args) {14        System.out.println("Hello Eolink");15    }16 }


体验地址:IDEA 工具插件 Eolink ApiKit