SpringBoot接入Knife4j接口文档

在这里插入图片描述

0.介绍

1) Knife4j是什么

Knife4j是Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,有着比Swagger更为美观的UI以及功能。

例如以下效果图:

image-20240518120553328

image-20240518120718512

2) 官方链接

官网:Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)

代码:xiaoymin/knife4j: Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution (github.com)

3)SpringBoot版本兼容性

以下为简略的对应版本:

Spring Boot版本Knife4j Swagger2规范Knife4j OpenAPI3规范
1.5.x~2.0.0<Knife4j 2.0.0>=Knife4j 4.0.0
2.0~2.2Knife4j 2.0.0 ~ 2.0.6>=Knife4j 4.0.0
2.2.x~2.4.0Knife4j 2.0.6 ~ 2.0.9>=Knife4j 4.0.0
2.4.0~2.7.x>=Knife4j 4.0.0>=Knife4j 4.0.0
>= 3.0>=Knife4j 4.0.0>=Knife4j 4.0.0

更详细的介绍查看官网即可:

Knife4j版本参考 | Knife4j (xiaominfo.com)

接下来以 SpringBoot 2.7.6 + Knife4j 4.4.0 作为示例,介绍一些常用的功能。

1.SpringBoot整合Knife4j

1)引入依赖

这里选择的SpringBoot版本是2.7.6

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

2)运行项目

实际测试发现无需其他配置,引入依赖后运行项目,进入ip:port/doc.html页面即可访问接口文档。

以下仅为示例,注解演示的时候代码和下方的会有区别。

注意:ReqesutMapping注册的接口,会被识别为多个,建议接口使用@GetMapping等特定方式

image-20240518154153932

上图效果对应的Controller代码如下:

@Controller
public class BasicController {

    // http://127.0.0.1:8080/hello?name=lisi
    @GetMapping("/hello")
    @ResponseBody
    public String hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return "Hello " + name;
    }

    // http://127.0.0.1:8080/user
    @RequestMapping("/user")
    @ResponseBody
    public User user() {
        User user = new User();
        user.setName("theonefx");
        user.setAge(666);
        return user;
    }

    // http://127.0.0.1:8080/save_user?name=newName&age=11
    @RequestMapping("/save_user")
    @ResponseBody
    public String saveUser(User u) {
        return "user will save: name=" + u.getName() + ", age=" + u.getAge();
    }

    // http://127.0.0.1:8080/html
    @RequestMapping("/html")
    public String html() {
        return "index.html";
    }

    @ModelAttribute
    public void parseUser(@RequestParam(name = "name", defaultValue = "unknown user") String name
            , @RequestParam(name = "age", defaultValue = "12") Integer age, User user) {
        user.setName("zhangsan");
        user.setAge(18);
    }
}

实体类:

public class User {

    private String name;

    private Integer age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

2.常用注解

此处仅以个人工作和学习的常用场景和属性示例,每个注解可能有多个属性,详细说明请参考文档和代码。

1) @Tag

位置:使用在Controller类上

@Controller
@Tag(name = "BasicController - 基本控制器")
public class BasicController {
    ...

效果:对应文档中的Tag名字,即红框内容,不加Tag的话此处名字为basic-controller

image-20240518154553338

2) @Operation

位置:使用在方法上

  	@GetMapping("/hello")
    @ResponseBody
    @Operation(summary = "say hello")
    public String hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return "Hello " + name;
    }

效果:使用summary修改方法的描述信息

image-20240518160559457

3) @Parameter

位置:使用在参数上或者方法上

    @GetMapping("/hello")
    @ResponseBody
    @Operation(summary = "say hello")
    public String hello(@Parameter(description = "用户名") @RequestParam(name = "name", defaultValue = "unknown user") String name) {
        return "Hello " + name;
    }

    @GetMapping("/user/{id}")
    @ResponseBody
    @Operation(summary = "获取用户信息")
    @Parameters({
            @Parameter(name = "id", description = "用户ID", required = true, example = "1234567890"),
            @Parameter(name = "name", description = "用户名", required = true, example = "theonefx")
    })
    public User getUesr(@PathVariable("id") Long id, @RequestParam String name) {
        User user = new User();
        user.setName(name);
        user.setAge(22);
        user.setId(id);
        return user;
    }

效果:

注意这里的示例值,是读取的@RequestParam的

image-20240518161411620

这里的示例值是@Parameter里的

image-20240518161446386

4) @Schema

位置:使用在实体类上及其属性上

@Schema(description = "User实体类")
public class User {

    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户名")
    private String name;

    @Schema(description = "用户年龄")
    private Integer age;
...

效果:

image-20240518162206328

这里的注解不仅对请求中的会有效果,也会影响包含此实体的响应的效果。

image-20240518162352945

X) 汇总

个人常用汇总:

注解属性描述
@Tagname使用在接口类上,用来影响接口文档一级标签的描述信息
@Operationsummary使用在接口上,影响接口文档二级标签的接口描述信息
@Parameterdescription使用在请求参数或者接口上(需要配合@Parameters),影响接口文档的请求参数-参数说明
@Schemadescription使用在实体类上,影响包含实体类的请求和响应的参数说明

image-20240518163550953

FAQ

1.接口已经定义好,但是在接口文档里找不到

检查下接口有没有@ResponseBody注解

  • 17
    点赞
  • 10
    收藏
    觉得还不错? 一键收藏
  • 2
    评论
Spring Boot是一种便捷的框架,它可以快速地搭建Java应用程序,并且它对于集成其他组件和框架也十分方便。而Knife4j则是一种集成度很高的API文档工具,它可以将接口文档Swagger的基础上大幅度优化。在Spring Boot中使用Knife4j整合API文档也非常简单。 首先,我们需要在Spring Boot的项目中引入Knife4j依赖,可以在pom.xml文件中加入以下代码: ``` <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.2.7</version> </dependency> ``` 这样Knife4j就会被自动集成到Spring Boot的应用中。 接下来,我们需要在Controller方法上增加注解,并且配置一些信息才能生成接口文档。 ``` @GetMapping("/hello") @ApiOperation(value = "示例API接口", notes = "这是一个示例API接口") @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用户名", required = true, dataType = "String", paramType = "header") }) public String hello(@RequestHeader String name){ return "Hello, " + name + "!"; } ``` 其中@GetMapping是Spring Boot的注解,用于标记这是一个GET请求。@ApiOperation和@ApiImplicitParams则是Knife4j的注解,它们分别用于注释方法和方法参数的信息。 最后,在启动Spring Boot应用后,访问http://localhost:8080/doc.html 就可以看到生成的接口文档了。这个文档列表会列出所有接口的URL、HTTP方法、请求参数、响应结果等信息,非常直观和有用。通过Knife4j可以使API文档生成更加高效、直观,方便开发者理解和调用接口。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值