JApiDocs|SpringBoot集成JApiDocs用以生成API文档

news2024/11/18 6:00:42

框架简介

效果图

JApiDocs和Swagger都是用于生成API文档的工具，它们各自有一些优点。下面是JApiDocs相较于Swagger的几个优点：

简单易用：JApiDocs相对来说更加简单易用，配置和使用都比较简单明了。它使用Java注解来描述API信息，而不需要额外的配置文件。

代码友好：JApiDocs直接与源代码进行交互，不需要通过额外的配置文件或注解来描述API文档信息。它通过扫描代码中的注释来生成API文档，提供了更加直观和代码友好的方式。

灵活性：JApiDocs提供了丰富的自定义选项，可以根据需要灵活地配置生成的文档内容和样式。可以通过自定义注解、自定义解析器等来满足不同的需求。

减少冗余代码：JApiDocs在生成API文档时，可以通过继承和重写的方式，减少冗余代码的编写。可以将公共的API信息提取到父类或接口中，子类或实现类中只需覆盖需要变更的部分，避免了重复的代码编写。

无侵入性：JApiDocs对代码的侵入性较低，只需要在需要生成文档的地方添加相应的注释或注解即可。不需要修改代码的原有逻辑。

需要注意的是，JApiDocs并不是像Swagger那样成熟和广泛使用的API文档工具，所以在选择时需要考虑自身的需求和项目的实际情况。

详细步骤

pom文件中添加Swagger依赖

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

在Spring Boot启动文件中书写配置（或任意一个main方法下运行）：

需要修改API文档生成的目录，自己自定义路径！

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;

@SpringBootApplication
@MapperScan("com.neusoft.elementplusboot.mapper")
public class ElementplusbootApplication {
    public static void main(String[] args) {
        SpringApplication.run(ElementplusbootApplication.class, args);
        
        DocsConfig config = new DocsConfig();
        config.setProjectPath("D:\\Programming\\Code\\eclipseCode\\elementplusboot"); //项目根目录
        config.setProjectName("ElementPlusBoot"); //项目名称
        config.setApiVersion("V1.0");       //声明该API的版本
        config.setDocsPath("D:\\Programming\\Code\\eclipseCode\\elementplusboot\\JApiDocs"); //生成API文档所在目录
        config.setAutoGenerate(Boolean.TRUE);  //不使用就只导出声明了@ApiDoc的接口
        Docs.buildHtmlDocs(config); //执行生成文档
    }
}

在实体类上添加注释

两种注解方式都可以使用！

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;

/**
 * 用户实体
 * @author PaperFish
 *
 */
public class Users {

	@TableId(value="uid",type=IdType.AUTO)
	private Integer uid; //用户编号
	private String uname; //用户姓名
	private Integer uage; //用户年龄
	private Integer usex; //用户性别
	
	@Override
	public String toString() {
		return "Users [uid=" + uid + ", uname=" + uname + ", uage=" + uage + ", usex=" + usex + "]";
	}
	public Integer getUid() {
		return uid;
	}
	public void setUid(Integer uid) {
		this.uid = uid;
	}
	public String getUname() {
		return uname;
	}
	public void setUname(String uname) {
		this.uname = uname;
	}
	public Integer getUage() {
		return uage;
	}
	public void setUage(Integer uage) {
		this.uage = uage;
	}
	public Integer getUsex() {
		return usex;
	}
	public void setUsex(Integer usex) {
		this.usex = usex;
	}

}

在控制层需要生成API的类及方法上添加注释

更多高级配置请去官网查看注解的使用：https://japidocs.agilestudio.cn/#/zh-cn/

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.github.pagehelper.Page;
import com.github.pagehelper.PageHelper;
import com.neusoft.elementplusboot.po.Users;
import com.neusoft.elementplusboot.service.UsersService;

import io.github.yedaxia.apidocs.ApiDoc;


/**
 * 用户管理接口
 * @author PaperFish
 *
 */
@RestController
@RequestMapping("/usersController")
public class UsersController {

	@Autowired
	UsersService usersService;

	/**
	 * 分页获取所有用户信息
	 * 
	 * @description 根据页码及页中数量获取用户信息
	 * @param page 页码
	 * @param pageSize 页中数量
	 * @param uname 用户姓名
	 * 
	 */
	@ApiDoc(stringResult = "{total:'', list:'{}'}")
	@GetMapping("/getAllUsers")
	public Map<String, Object> getAllUsers(int page, int pageSize, String uname) {
		// int startpPage = (page - 1) * pageSize;
		Page<Object> startPage = PageHelper.startPage(page, pageSize);
		List<Users> usersList = usersService.getAllUsers(uname);

		Map<String, Object> map = new HashMap<String, Object>();
		map.put("list", usersList); // 记录返回内容
		map.put("total", startPage.getTotal()); // 记录数据条数

		return map;
	}

	/**
	 * 新增用户
	 * 
	 * @description 新增用户信息
	 * @param users 用户对象
	 * 
	 */
	@PostMapping("/saveUsers")
	public int saveUsers(@RequestBody Users users) {
		return usersService.saveUsers(users);
	}

	/**
	 * 更新用户
	 * 
	 * @description 更新用户信息
	 * @param users 用户对象
	 * 
	 */
	@PutMapping("/updateUsers")
	public int updateUsers(Users users) {
		return usersService.updateUsers(users);
	}

	/**
	 * 删除用户
	 * 
	 * @description 删除用户信息
	 * @param uid 用户编号
	 * 
	 */
	@DeleteMapping("/deleteUsers")
	public int deleteUsers(Integer uid) {
		return usersService.deleteUsers(uid);
	}

}