Java最安全的接口文档生成工具，零注解侵入，大公司都在用

简介

smart-doc是一个java restful api文档生成工具，smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照java标准注释的写，smart-doc就能帮你生成一个简易明了的markdown 或是一个像GitBook样式的静态html文档。如果你已经厌倦了swagger等文档工具的无数注解和强侵入污染，那请拥抱smart-doc吧！

特点

• 
  

  零注解、零学习成本、只需要写标准java注释。

  
  

• 
  

  基于源代码接口定义自动推导，强大的返回结构推导。

  
  

• 
  

  支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。

  
  

• 
  

  支持Callable,Future,CompletableFuture等异步接口返回的推导。

  
  

• 
  

  支持JavaBean上的JSR303参数校验规范。

  
  

• 
  

  对json请求参数的接口能够自动生成模拟json参数。

  
  

• 
  

  对一些常用字段定义能够生成有效的模拟值。

  
  

• 
  

  支持生成json返回值示例。

  
  

• 
  

  支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。

  
  

• 
  

  支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman json。

  
  

• 
  

  轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。

  
  

• 
  

  开放文档数据，可自由实现接入文档管理系统。

  
  

• 
  

  支持导出错误码和定义在代码中的各种字典码到接口文档。

  
  

教程

创建测试项目，引入smart-doc依赖，pom.xml代码如下：

com.github.shalousungroupId> smart-docartifactId> 1.8.1version> testscope> dependency>

创建接口参数实体对象，代码如下：

package com.july.test.entity;
import com.july.test.jenum.SexEnum; import lombok.Data;
/** * 测试用户信息 * @author zqk * @since 2020/1/17 */ @Data public class UserInfo {
/** * 用户id */ private Long id; /** * 姓名 */ private String username; /** * 密码 * @ingore */ private String password; /** * 性别 */ private SexEnum sex;
}

创建测试接口，代码如下：

package com.july.test.controller;
import com.july.test.config.ApiResult; import com.july.test.entity.UserInfo; import org.springframework.web.bind.annotation.*;
import java.util.ArrayList; import java.util.List;
/** * 测试用户控制器 * @author zqk * @since 2020/1/17 */ @RestController @RequestMapping("/user") public class UserInfoController {
/** * 获取用户信息 * @param userInfo * @return * @author zqk * @since 2020/1/17 11:26 上午 * @deprecated */ @PostMapping("/getUserInfo") public ApiResult getUserInfo(@RequestBody UserInfo userInfo){ return ApiResult.ok(userInfo); }
/** * 获取所有用户信息 * @param userInfo * @return com.july.test.config.ApiResult> * @author zqk * @since 2020/1/24 9:42 下午 */ @PostMapping("/getUserInfoList") public ApiResult> getUserInfoList(@RequestBody UserInfo userInfo){ List userInfoList = new ArrayList<>(); userInfoList.add(userInfo); return ApiResult.ok(userInfoList); }
}

创建单元测试，执行接口文档生成，代码如下：

package com.july.test;
import com.power.doc.builder.ApiDocBuilder; import com.power.doc.builder.HtmlApiDocBuilder; import com.power.doc.model.ApiConfig; import org.junit.jupiter.api.Test;
/** * 自动生成接口文档 * @author zqk * @since 2020/01/06 */ public class MarkDownTest {
@Test public void Test(){ ApiConfig config = new ApiConfig(); //服务地址 config.setServerUrl("http://localhost:8010"); //生成到一个文档 config.setAllInOne(true); //采用严格模式 config.isStrict(); //文档输出路径 config.setOutPath("/Users/mac/Downloads"); //生成HTML接口文档 //HtmlApiDocBuilder.buildApiDoc(config); //生成MarkDown接口文档 ApiDocBuilder.buildApiDoc(config); }
}

生成的HTML接口文档如下图：

生成MarkDown接口文档如下图：

以上就是通过smart-doc自动生成接口文档的过程，只需要写相应的注释即可生成接口文档，并且smart-doc还有很多小功能，小伙伴们可以去尝试测试。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。