springboot中,接口文档自动生成的两种方式

演示环境

springboot:2.5.2

jdk:1.8

springfox-swagger2:3.0.0

knife4j-spring-boot-starter:3.0.3

一、Swagger2 + Knife4j

1、Swagger2:用于设计、构建和文档化RESTful API的开源框架

2、Knife4j:基于Swagger构建的开源API文档工具,它提供了一套简洁美观的UI界面,可以更好地呈现和管理API文档

官网:knife4j

1、添加依赖

java 复制代码
	<!-- swagger2依赖 -->
	<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>

	<!-- knife4j依赖 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

2、创建接口文档配置类 - SwaggerConfig.java

ps:类名可自定义,也可以在yml中配置,可自行参考knife4j的官方文档

java 复制代码
import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build()
                .groupName("默认分组");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact(
                        "作者名称",
                        "作者个人网站地址",
                        "作者邮箱"
                ))
                .title("karl-接口文档标题")
                .description("karl的接口文档描述")
                .version("1.0.0")
                .termsOfServiceUrl("接口服务地址")
                .build();
    }
}

生成后,效果如下

3、新建数据模型类 - IndexModel.java

ps:这里是首页数据模型类,类的名称可以自定义,我这里的首页用于演示,实际开发以业务为准

java 复制代码
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

// 这里使用了 lombok
// 也可以使用原始的方式用IDEA生成这些方法
// 包括:无参构造函数、get方法、set方法
@NoArgsConstructor
@Getter
@Setter
public class IndexModel {

    // 属性描述
    @ApiModelProperty("用户输入的字符串")
    // 隐藏该参数,便于在控制器中用 @ApiImplicitParam 来控制文档显示的请求参数
    @ApiParam(hidden = true)
    private String str;

}

生成后,效果如下

4、新建应答消息类 - IndexMessage.java

ps:这里是首页应答消息类,类的名称可以自定义,我这里的首页用于演示,实际开发以业务为准

java 复制代码
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

// 这里使用了 lombok
// 也可以使用原始的方式用IDEA生成这些方法
@NoArgsConstructor
@Getter
@Setter
// 模型对象描述
@ApiModel(value = "首页接口返回信息")
public class IndexMessage {

    // 属性描述
    @ApiModelProperty("返回的字符串内容")
    // 隐藏该参数
    @ApiParam(hidden = true)
    private String resultStr;

}

生成后,效果如下

5、新建首页控制器 - IndexController.java

ps:这里是首页控制器类,类的名称可以自定义,我这里的首页用于演示,实际开发以业务为准

注意:IndexModel 和 IndexMessage 需要你自己手动导一下包

java 复制代码
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// 接口文档一级菜单标题
@Api(tags = {"首页"})
@RestController
// 一级请求路径
@RequestMapping("/Index")
public class IndexController {

    // 接口文档二级菜单标题、说明
    @ApiOperation(value = "首页演示接口", notes = "首页-HelloWorld-接口说明")
    // 接口的请求参数,可以根据 Model类的属性随意控制
    // 但是要根据实际业务来,本接口需要哪些参数就写哪些
    @ApiImplicitParams({
            @ApiImplicitParam(name = "str", value = "用户输入的字符串", paramType = "query", required = true)
    })
    // 二级请求路径
    @PostMapping("/HelloWorld")
    // 接口方法
    // 参数:IndexModel - 首页请求数据模型类
    // 返回:IndexMessage - 首页应答消息类
    public IndexMessage HelloWorld(IndexModel indexModel) throws Exception {
        // 创建 首页应答消息对象
        IndexMessage message = new IndexMessage();
        // 将 用户传入的字符串 与 helloWorld 拼接,并赋值给应答对象的属性
        message.setResultStr("helloWorld " + indexModel.getStr());
        // 返回 首页应答消息对象
        return message;
    }

}

生成后,效果如下

6、启动项目,访问接口文档

knife4j的文档地址:springboot项目地址/doc.html

ps:也可以在这里调试接口

二、Apifox + Apifox Helper 插件

ps:需要创建 Model类、Message类 和 控制器类;描述要写到位,不然文档不会生成描述

1、下载 Apifox -> 注册 -> 登录

2、新建一个团队,名称自定义

3、新建一个项目,名称自定义

4、创建 API访问令牌

注意:点击生成后,会显示生成的令牌,一定要记住了再点击关闭,不然关闭后就无法查看了,那就只能重新创建一个令牌了

5、打开 IDEA,搜索 Apifox Helper 插件,并下载

6、下载完毕后,点击立即重启以生效

这时候在设置里面就能看到插件的配置项了

7、插件配置

8、获取项目ID

9、使用插件自动生成并上传文档到 Apifox

ps:在控制器中 或 右击控制器 用于生成单个控制器的接口文档

如果右击 controller 包,用于生成所有控制器的接口文档

ps:第一次上传需要输入 项目ID,然后点击 OK

ps:控制台会打印详细的日志信息,看到 Imported Successfully 表示上传成功

10、打开 Apifox 查看接口信息

至此,本教程完毕!

结语

希望对你能有所帮助,有问题可以私信或下方留言给我

相关推荐
自由的疯11 小时前
Java 如何学习Docker
java·后端·架构
自由的疯11 小时前
Java Docker本地部署
java·后端·架构
007php00711 小时前
猿辅导Java面试真实经历与深度总结(二)
java·开发语言·python·计算机网络·面试·职场和发展·golang
摇滚侠11 小时前
Spring Boot 3零基础教程,WEB 开发 内容协商机制 笔记34
java·spring boot·笔记·缓存
一勺菠萝丶11 小时前
在 macOS 上用 Docker 为 Java 后端 & 常见开发需求搭建完整服务(详尽教程)
java·macos·docker
顾漂亮11 小时前
JVM底层攻坚
java·jvm·spring
编程岁月11 小时前
java面试-0215-HashMap有序吗?Comparable和Comparator区别?集合如何排序?
java·数据结构·面试
木井巳11 小时前
[Java数据结构与算法]详解排序算法
java·数据结构·算法·排序算法
Json____11 小时前
学习springBoot框架-开发一个酒店管理系统,来熟悉springboot框架语法~
spring boot·后端·学习
没有bug.的程序员12 小时前
分布式架构未来趋势:从云原生到智能边缘的演进之路
java·分布式·微服务·云原生·架构·分布式系统