java快速生成接口文档方法总结_小码农叔叔的博客-程序员宅基地_java接口文档生成

技术标签: 技术总结  swagger生成接口文档  java生成接口文档  java快速生成接口文档  japidocs生成接口文档  

前言

常常在项目收尾阶段,客户需要项目的接口文档,或者是一个大的sass平台,各个产品之间互相调用的时候,需要对方提供接口文档

通常来说,接口文档属于产品的技术沉淀,是一个长期积累的过程,然而,很多时候,开发阶段并不会想的那么多,结果到了需要接口文档的时候总是疲于应付,情急之下,往往采用最笨拙的办法,就是对照着项目代码,一个个拷贝吧

下面针对这个情况,小编这里给出2种简单、快捷而适用的解决方案,帮助你快速解决这个烦恼吧

方案一,使用japidocs

这是一种最简单也最高效的快速生成接口文档的方式,也是对既有项目改造代价最小的方式

  • 可用于生成spring boot api文档
  • 读取JAVA DOC注释,无需额外的代码改造

基本用法

1、添加依赖

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

2、在工程的某个包下面,添加一个类

在这里插入图片描述
如这里有一个TestApi的类,里面添加一个main方,使用如下模板代码即可,自己使用时,需要简单修改几处,项目根目录,生成文档的目录

public class TestApi {

    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        // 项目根目录
        config.setProjectPath("E:\\学习代码\\assmblyone\\web");
        // 项目名称
        config.setProjectName("Assembly");
        // 声明该API的版本
        config.setApiVersion("V2.0");
        // 生成API 文档所在目录
        config.setDocsPath("E:\\学习代码\\assmblyone");
        // 配置自动生成
        config.setAutoGenerate(Boolean.TRUE);
        // 执行生成文档
        Docs.buildHtmlDocs(config);
    }

}

这里假如工程中有一个UserController接口类

@RestController
@RequestMapping(value = "/api2doc")
public class UserController {

    /**
     * 获取用户讯息
     * @return
     */
    @ApiComment("获取用户。")
    @GetMapping("/getUser")
    public User getUser() {
        User user = new User();
        user.setGroup("group1");
        user.setName("first-group");
        return user;
    }

    /**
     * 新增用户
     * @param group 用户组名称
     * @param name  基础名称
     * @return
     */
    @ApiComment("添加新用户")
    @GetMapping(name = "新增用户", value = "/user")
    public String addUser(String group, String name) {
        return " group:" + group + " ==== " + "name :" + name;
    }

}

有一个实体类User

@Data
public class User {

    /**
     * id主键
     */
    private Long id;

    /**
     * 用户名
     */
    private String name;

    /**
     * 账号密码
     */
    private String password;

    /**
     * 用户所在的组
     */
    private String group;

    /**
     * 用户类型
     */
    private UserType type;

    /**
     * 是否已删除
     */
    private Boolean deleted;

    /**
     * 创建时间
     */
    private Date createTime;

}

为了让生成的文档看起来更加完善,controller的各个接口名称,以及实体中的字段等注释一定要尽可能完整

然后运行一下main方法,生成一下吧
在这里插入图片描述

然后会发现,在指定的文件目录下,针对项目中的各个controller类,生成了html文档,不妨打开看一下吧

在这里插入图片描述

这个效果也算很良心了,到这里是不是值得小小庆贺下呢,当然对于japidocs来说,功能可不止这些,有兴趣的同学可以继续深入研究下呢

方案2,swagger + knife4j

相信使用过springboot框架的同学对swagger插件一定不陌生,springboot中集成swagger 可以帮助我们快速进行接口调试,以提升开发人员的接口调试效率

但是单纯使用swagger的话,效果往往并不理想,比如想使用swagger导出一份可以交付的接口文档的话,就有点困难了,这就需要swagger 配合knife4j一起使用了

生成步骤

1、导入相关依赖

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
		
		<!--swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>${swagger-bootstrap-ui.version}</version>
        </dependency>

2、添加swagger配置类

@Configuration
@EnableSwagger2
@EnableKnife4j
public class ApiSwagger2 {

    @Bean
    public Docket createRestBmbsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("users")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.congge.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户相关API")
                .version("1.0")
                .build();
    }

}

3、启动项目之后分别访问如下地址

http://localhost:8048/swagger-ui.html
在这里插入图片描述

这个界面想必大家一定很熟悉了,这就是swagger界面,可以在这个上面快速进行接口调试工作

http://localhost:8048/doc.html#/home
在这里插入图片描述

在这里插入图片描述

这个界面就是集成了knife4j之后展示出来的效果,这个效果看起来是不是更好了点

在这里插入图片描述

点就到文档管理菜单栏,提供了几种常用的可用于下载的接口文档方式,比如我们以html为例,点击下载,然后看一下效果如何
在这里插入图片描述

方案3,开源的接口文档生成工具

这里推荐2种

1、japi ,这是一个开源项目,git上面可以下载之后本地运行,需要安装node环境

这里推荐一篇文章,可供参考:https://www.jianshu.com/p/8ac211d9c6d3

2、使用ApiPost工具快速生成在线接口文档

ApiPost是一个支持团队协作,并可直接生成文档的API调试、管理工具。它支持模拟POST、GET、PUT等常见请求,是后台接口开发者或前端、接口测试人员不可多得的工具 。使用者不仅可以利用apiopst调试接口,还可以书写相关注释(接口文档),方便的生成可读性好、界面美观的在线接口文档。

使用ApiPost需要下载官方安装包,然后本地安装即可,官网软件下载地址:https://www.apipost.cn/

关于ApiPost,由于其功能的强大,被很多开发人员,测试人员以及项目管理人员等广泛使用,在小编所在的产品测试团队,不少测试同事使用这款工具

对小编来说,所有麻烦的事情一律都采用保守的态度,但是这款工具确实值得推荐和学习,界面风格很相PostMan,这里有一篇详细介绍ApiPost使用的文档,提供参考和学习:https://www.cnblogs.com/gina61/articles/12931356.html

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/zhangcongyi420/article/details/119151683

智能推荐

leetcode 304. Range Sum Query 2D - Immutable_蓝羽飞鸟的博客-程序员宅基地

Given a 2D matrix matrix, find the sum of the elements inside the rectangle defined by its upper left corner (row1, col1) and lower right corner (row2, col2).Example:Given matrix = [[3, 0, 1, 4, 2...

sql之旅-T-SQL创建表和删除表_IT探花的博客-程序员宅基地_sql创建表

创建表语法:CREATE TABLE tableName(    ID INT  NOT NULL,    NAME VARCHAR(20)  NOT NULL,    SEX BIT  NOT NULL,    ADDRESS CHAR(25),    PRIMARY KEY (ID));验证表是否创建成功:输入命令:exec sp_columns tableName;查看结果:返回每一列的相关...

图像分割综述:FCN、U-Net、PSPNet、DeepLab_紫芝的博客-程序员宅基地

图像分割综述什么是图像分割?图像分割在CV领域的研究图像语义分割用到的技术FCNU-Net&amp;PSPNetDeepLab系列Graph-based 分割实例分割图像分割的类型图像分割的应用场景语义分割算法的基本概念语义分割算法的基本流程语义分割的性能指标什么是图像分割?What is image segmentation task?图像分割在CV领域的研究Why image segmentation task is import ?图像语义分割用到的技术编程语言:Pytho

函数依赖闭包及求闭包的算法_leopardaa521的博客-程序员宅基地_2、函数依赖的闭包的定义是什么?通过什么样的方法求解?计算f的闭包时存在什么样

F 的闭包: 在关系模式 R , F> 中为 F 所逻辑蕴含的函数依赖的全体叫作 F 的闭包,记为 F + 。   属性集 X 关于函数依赖集 F 的闭包: 设 F 为属性集 U 上的一组函数依赖, X Í U , XF + ={ A|X → A 能由 F 根据 Armstrong 公理导出 } , XF + 称为属性集 X 关于函数依赖集 F 的闭包.  

Linux上卸载jdk,安装jdk,配置jdk环境详细说明_芒果桔子西瓜汁的博客-程序员宅基地

一.准备工具Linux系统,SSH远程工具(XShell,MobaXterm),jdk安装包二,检查及卸载自带的jdk以及rpm安装的jdk1.查看现有的jdk版本,其命令:rpm -qa|grep jdk2.卸载现有的jdk,其命令:rpm -e --nodeps jdk名称3.卸载rpm安装的jdk,其命令:rpm -e --nodeps jdk名称4.找到jdk安装目...

学习笔记(04):2020软考网络工程师--基础知识视频教程-系统开发与运行(二)_lh785803549的博客-程序员宅基地

基础知识视频教程内容包括:数据通信基础、局域网、城域网、广域通信网、网络互连与互联网等内容,为顺利通过软考和自身能力提高打下坚实基础,让小白直变网络工程师...

随便推点

EasyExcel自定义样式生成Excel_光阴不负卿的博客-程序员宅基地

EasyExcel是一个基于Java的简单、省内存的读写excel的开源项目。在尽可能节约内存的情况下支持读写百M的excel.官方文档地址为:https://www.yuque.com/easyexcel/doc/easyexcelEasyExcel生成excel1、定义实体类(模板)import com.alibaba.excel.annotation.ExcelProperty;import com.alibaba.excel.annotation.write.style.Col..

Ubuntu16.04 安装dlib face_recognition_huangle63的博客-程序员宅基地

http://www.pyimagesearch.com/2017/03/27/how-to-install-dlib/Installing CMake, Boost, Boost.Python, and X11 can be accomplished easily with apt-get :$ sudo apt-get install build-essential cmake$ sud

The selection cannot be run on any server解决办法_临水逸的博客-程序员宅基地

the selection cannot be run on any server解决办法url 只要将version=”3.0”改成version=”2.5”,然后重启eclipse即可!!!具体操作步骤:找到你的eclipse:D:\eclipse\workspace-jee\项目名称.settings\org.eclipse.wst.common.project.facet.

Linux 常用指令学习整理_叫我海王大人的博客-程序员宅基地

记录常使用的一些Linux操作指令,学习视频来自https://www.bilibili.com/video/av14184325/。

推荐文章

热门文章

相关标签