Java接口文档神器学习及使用JApiDocs,附与Swagger的简单对比

JApiDocs的优势

目前我用过的接口文档工具只有Swagger和JApiDocs,Swagger出现地比较早,它的使用方法在网上也更容易搜到,也是我最开始用的工具。它相对于JApiDocs最大的优点就是网上可供参考的资料更多更详细,并且界面也是更具体更美观,缺点也是比较明显的,使用Swaager不但需要一大串配置代码,并且每个Controller、Api上都要写很长一串注解代码,像我这样比较懒的人看见这些都要头大。而JApiDocs只需要引入pom依赖、在main文件上写上短短几行启动配置就能完美实现接口文档,完全称得上是懒人神器了。

JApiDocs和Swagger界面对比

通过图片对比,可以明显看到Swagger的界面更具体更美观,而JApiDocs的界面看上去就比较单调,但是也足够用来做前后端交互

JApiDocs简单使用代码

首先pom文件引入依赖

    <dependency>
            <groupId>io.github.yedaxia</groupId>
            <artifactId>japidocs</artifactId>
            <version>1.4</version>
        </dependency>

        DocsConfig config = new DocsConfig();
        // 项目根目录(文件夹目录)
        config.setProjectPath("E:\\ApiDocsDemo");
        // 项目名称
        config.setProjectName("ApiDocsDemo");
        // 声明该API的版本
        config.setApiVersion("V1.0");
        // 生成API 文档所在目录
        config.setDocsPath("E:\\IApiDocsDemo\\apidocs");
        // 配置自动生成
        config.setAutoGenerate(Boolean.TRUE);
        // 执行生成文档
        Docs.buildHtmlDocs(config);

这样基本的配置就完成了,接下来就只需要正常在Controller层上写代码即可,只需要写必要的注解和代码注释,并不像Swagger那样还要为文档工具单独写上N多代码,下面分别放两段用JApiDocs和Swagger2的接口代码做比较

/**
 * 智能作业接口
 */
@RestController
@RequestMapping("/quartz")
public class QuartzController {
    @Autowired
    private QuartzService quartzService;

    /**
     * 新增计划
     * @param jobName 计划名
     * @param jobGroupName 计划组名
     * @param triggerName 触发按钮名
     * @param triggerGroupName 触发按钮组名
     * @param cron cron表达式
     * @param energyKind 能源类型
     * @param groupNo 分组编号
     * @param beginReadTime 开始时间
     * @param endReadTime 结束时间
     * @param ClassName 类名
     * @return
     */
    @PostMapping("/startquartzplan")
    @SneakyThrows
    public boolean startQuartzPlan(@RequestParam("jobName")String jobName,
                                   @RequestParam("jobGroupName")String jobGroupName,
                                   @RequestParam("triggerName")String triggerName,
                                   @RequestParam("triggerGroupName")String triggerGroupName,
                                   @RequestParam("cron")String cron,
                                   @RequestParam("energyKind")String energyKind,
                                   @RequestParam("groupNo")String groupNo,
                                   @RequestParam("beginReadTime")String beginReadTime,
                                   @RequestParam("endReadTime")String endReadTime,
                                   @RequestParam("ClassName")String ClassName){
        quartzService.StartScheduler(jobName,jobGroupName,triggerName,triggerGroupName,cron,energyKind,groupNo,beginReadTime,endReadTime,ClassName);
        return  true;
    }
}

这是使用JApiDocs的接口代码段,可以看到除了必要的一些注释以外基本没有任何多余的代码

@RestController
@RequestMapping(value = "/api")
@Api(value = "Controller|a test")
public class TFMysqlController {
    @Autowired
    private mynewinfoservice mynewinfoservice;
    @ApiOperation(value = "增加用户",notes = "增加用户表内容")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", required = true, name = "no", dataType = "Int", value = "编号"),
            @ApiImplicitParam(paramType = "query", required = true, name = "name", dataType = "String", value = "姓名"),
            @ApiImplicitParam(paramType = "query", required = true, name = "age", dataType = "Int", value = "年龄"),
            @ApiImplicitParam(paramType = "query", required = true, name = "sex", dataType = "String", value = "性别")
    })
    @RequestMapping(value = "/post/user", method = RequestMethod.POST)
    public boolean addUser(Mynewinfo mynewinfo) {
        try {
            System.out.println("开始插入新信息...");
            mynewinfoservice.addUser(mynewinfo);
            System.out.println("插入成功");
            return true;
        }catch (Exception ex){
            ex.printStackTrace();
            return false;
        }
    }
}

这是使用Swagger2的接口代码,除了正常实现接口要写的东西还有一堆用来实现Swaager的注解要写,对于我这种比较懒惰的人来讲可以说是又臭又长

最后放出该工具作者的官方使用说明连接

链接: JApiDocs官方文档.