springboot项目如何使用JApiDocs生成接口文档

不念不忘少年蓝@ 2022-10-31 04:25 243阅读 0赞

> `springboot项目如何使用JApiDocs生成接口文档`

> 第一步：添加依赖

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

> 第二步：配置参数
> 
> > 你可以在任意一个main入口运行下面的代码

DocsConfig config = new DocsConfig();
    config.setProjectPath("your springboot project path"); // 项目根目录
    config.setProjectName("ProjectName"); // 项目名称
    config.setApiVersion("V1.0");       // 声明该API的版本
    config.setDocsPath("your api docs path"); // 生成API 文档所在目录
    config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
    Docs.buildHtmlDocs(config); // 执行生成文档

> 编码规范  
> JApiDocs是通过解析Java源码来实现的，要使得JApiDocs正确工作，需要你在项目中的Controller书写遵循一定的编码规范。

`你可以结合源码中 SpringDemo 这个模块来对照理解。`

> 1.  添加必要的代码注释其中类注释会对应到一级接口分组，你也可以通过@description来指定分组名称；JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容。

> 代码示例

/** * 用户接口 */
    @RequestMapping("/api/user/")
    @RestController
    public class UserController { 
    
    
        /** * 用户列表 * @param listForm */
        @RequestMapping(path = "list", method = { RequestMethod.GET,  RequestMethod.POST}  )
        public ApiResult<PageResult<UserVO>> list(UserListForm listForm){ 
            return null;
        }
    
        /** * 保存用户 * @param userForm */
        @PostMapping(path = "save")
        public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){ 
            return null;
        }
    
        /** * 删除用户 * @param userId 用户ID */
        @PostMapping("delete")
        public ApiResult deleteUser(@RequestParam Long userId){ 
            return null;
        }
    }

> 亲自试一遍就知道生成什么样的文档了，具体使用参考官方文档

具体使用请参考官方文档：[https://japidocs.agilestudio.cn/][https_japidocs.agilestudio.cn]

[https_japidocs.agilestudio.cn]: https://japidocs.agilestudio.cn/