springboot项目集成swagger

本文介绍下，项目中如何集成swagger （注：此处用的是swagger3的版本）

使用的是springboot工程。讲到swagger，那就一般会一起集成knife4j，因为swagger原生的UI界面很不友好，而knife4j就方便很多。话不多说，直接开始

一、项目添加依赖：

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.6.0</version>
        </dependency>

二、访问地址：http://localhost:8080/swagger-ui/index.html 。 访问页面如下：

 这是swagger原生页面，有一些不太方便，比如无法快速查找某个接口，某个模块；

三、swagger常见的注解：

1、在controller的类上添加以下注解，表示对该接口整体描述。

@Tag(name = "讨论",description = "讨论相关接口")
public class DiscussController {

2、方法上添加如下注解，表示该接口的功能解释，当然它还有别的属性，可自行发掘

    @Operation(summary = "讨论详情")
    public ResponseEntity detail(Long did) {
    }

3、方法上添加如下注解，表示入参提醒

    @Parameters(value = {
            @Parameter(name = "msg",description = "消息"),
            @Parameter(name = "id",description = "id")
    })
    public ResponseEntity test(String msg,Integer id) {}

4、入参或者出参的类或属性上添加如下注解

@Data
@EqualsAndHashCode(callSuper = false)
@Schema(description = "用户入参DTO")
public class UserDTO {

    @Schema(description = "验证码")
    private String captcha;
}

引入knife4j

一、添加依赖：

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

二、官网地址：

 https://doc.xiaominfo.com/docs/quick-start

三、访问UI页面：http://localhost:port/doc.html

我们可以通过右上角有个搜索栏进行接口和模块搜索，快速定位接口。

在文档管理里面，可以通过设置全局参数设置，比如常见的token

 离线文档中也能生成相应的文档，发送给别人

 

以上就是集成swagger和knife4j