superJavaDoc 快速文档构建框架

superJavaDoc 快速文档构建框架

superJavaDoc 快速文档构建框架基于 Java 注释生成接口文档注释支持扩展接口框架支持扩展默认支持 markdown 和离线 / 在线 html 等格式的文档默认支持 spring mvc 规范默认支持 spri......

欢迎点击访问我的瞎几把整站点：复制未来

• 基于 Java 注释生成接口文档
• 注释支持扩展
• 接口框架支持扩展
• 默认支持 markdown 和离线 / 在线 html 等格式的文档
• 默认支持 spring mvc 规范
• 默认支持 spring-boot 直接内嵌启动

基于 SpringBoot 在线直接使用

1. 引入 Maven 依赖

<dependency>
    <groupId>com.uifuture</groupId>
    <artifactId>super-java-doc-starter</artifactId>
    <version>1.0.0</version>
</dependency>

2. 增加 EnableDoc 注解

在 Application 类上加上 EnableDoc 注解

@EnableDoc 
@SpringBootApplication
public class TestApplication {

    public static void main(String[] args) {
        SpringApplication.run(TestApplication.class, args);
    }
}

3.1 properties 配置文件

#在application.properties配置项目源码的位置,直接在项目里启动时,如果是单模块的maven项目,默认可以不配置
#是否启动XDoc,默认是true,因为可以不填
doc.enable=true 
#源码路径,多个时用英文逗号隔开，super-java-doc-test为项目模块名称。单模块项目可以将super-java-doc-test/去掉，直接使用src/main/java 
doc.sourcePath=super-java-doc-test/src/main/java  
#用于配置文档页面标题 
doc.title=在线接口文档  
#标识接口文档的版本号
doc.version=1.0   

3.2 yml 配置文件

doc:
  enable: true 
  title: 在线接口文档 
  sourcePath: super-java-doc-test/src/main/java 
  version: 1.0 

4 使用

以上配置就都写好了

跟着随便写几个 Controller 作为 Demo 接口, 便于直接浏览生成效果:

@Controller
@RequestMapping("admin/blogs")
public class BlogsController {
    @Resource
    private BlogsService blogsService;

    
    @PostMapping("add")
    @ResponseBody
    public ResultModel add(Blogs blogs) {
        blogsService.insert(blogs);
        return ResultModel.success();
    }

    
    @PostMapping("delete")
    @ResponseBody
    public ResultModel delete(@RequestParam Integer id) {
        blogsService.deleteById(id);
        return ResultModel.success();
    }

    
    @PostMapping("update")
    @ResponseBody
    public ResultModel update(Blogs blogs) {
        blogsService.updateById(blogs);
        return ResultModel.success();
    }

    
    @PostMapping("detail")
    @ResponseBody
    public ResultModel detail(@RequestParam Integer id) {
        Blogs blogs = blogsService.selectById(id);
        return ResultModel.success(blogs);
    }

    
    @PostMapping("list")
    @ResponseBody
    public ResultModel list(@RequestParam(defaultValue = "0") Integer page, @RequestParam(defaultValue = "0") Integer size) {
        PageHelper.startPage(page, size);
        List<Blogs> list = blogsService.selectAll();
        PageInfo pageInfo = new PageInfo(list);
        return ResultModel.success(pageInfo);
    }

}

直接启动项目, 敲入地址: http://localhost:8080/superJavaDoc/index.html

如下两个图，为部分展示内容。

2. 生成离线文档

支持 html:

@Test
public void buildMarkdown() {
    
    ByteArrayOutputStream out = new ByteArrayOutputStream();
    String rootDir = System.getProperty("user.dir");
    SuperJavaDoc xDoc = new SuperJavaDoc(rootDir + "/src/main/java/com/uifuture", new SpringWebFramework());
    xDoc.build(out, new MarkdownFormat());

    System.out.println(out.toString());
}

支持 markdown:

@Test
public void buildHtml() throws Exception {
    
    String userDir = System.getProperty("user.dir");
    FileOutputStream out = new FileOutputStream(new File(userDir, "api.html"));
    SuperJavaDoc xDoc = new SuperJavaDoc(userDir + "/src/main/java/com/uifuture", new SpringWebFramework());
    xDoc.build(out, new HtmlForamt());
}

注意: 生产环境不推荐开启此文，可能会消耗性能，所以在生成环境下，配置文件中配置如下即可:

doc.enable=false

项目地址：github.com/chenhaoxian…