1.引入依赖
创建项目后,在 pom.xml
文件中引入 Swagger3 的相关依赖。回忆一下,我们集成 Swagger2 时,引入的依赖如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
而在 Swagger3 中,我们不需要再引入两个不同的依赖了,我们只需要引入一个依赖就足够,具体引入的依赖如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
而这部分,Swagger2 和 Swagger3 就有所不同了,Swagger2 需要添加两项不同依赖,而 Swagger3 只用添加一项依赖就可以了。
除此之外还有一个依赖与上述Swagger3 功能一样:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.3</version>
</dependency>
1.1.springfox-boot-starter与springdoc-openapi-ui的区别
-
springfox-boot-starter:
- 这是Springfox团队开发的一个库,用于集成Swagger到Spring Boot项目中。
- 版本3.0.0是适用于Swagger 3的版本,支持Swagger 3的新特性和规范。
- 该库提供了一组注解和类,用于配置和生成Swagger文档,并提供了与Spring MVC集成的功能。
- 通常与Springfox的其他模块一起使用,如
springfox-swagger-ui
和springfox-swagger2
。
-
springdoc-openapi-ui:
- 这是一个由社区维护的库,用于集成OpenAPI(以前称为Swagger)到Spring Boot项目中。
- 版本1.6.3是适用于OpenAPI 3的版本,支持OpenAPI 3的新特性和规范。
- 该库提供了一组注解和类,用于配置和生成OpenAPI文档,并提供了一个集成了Swagger UI的Web界面。
- 与Springfox不同,springdoc-openapi-ui更专注于OpenAPI规范,提供了更多与OpenAPI规范对齐的功能和特性。
总的来说,如果你的项目使用Swagger 3(现在被重命名为OpenAPI 3),你可以选择使用 springfox-boot-starter
或者 springdoc-openapi-ui
,具体选择取决于你更喜欢哪种库的风格和功能。
1.2使用Knife4j作为UI界面时需要导入一下依赖:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.1.0</version>
</dependency>
com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter
是 Knife4j 对 Swagger 3 的增强,它也提供了自己的注解和配置。通常来说,Knife4j 提供了更丰富的 UI 功能和配置选项,使得生成的 API 文档更加易读和美观。
2. 配置Swagger
在Spring Boot项目中创建一个配置类SwaggerConfig
,并添加Swagger的配置信息。
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("进销存管理系统")
.contact(new Contact())
.description("我的API文档")
.version("v1"));
}
}
yaml文件配置如下:
#swagger3文档配置
springdoc:
swagger-ui:
enabled: true
#参数扁平化处理(swagger界面实体属性可以当做params参数正常显示)
default-flat-param-object: true
这样配置好了之后就可以正常使用注解了
使用注解方式如下:
接口controller:
@Slf4j
@Tag(name = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {
@Autowired
private UserManager userManager;
/**
* //TODD
* 系统登录
*
* @author:
* @date: 2024-04-05 13:03:40
* @param: * @param
* @return: ServiceVO
**/
@Operation(summary = "系统登录")
@PostMapping("/login")
public ServiceVO login(@RequestBody User user, HttpSession session) {
log.info("login user: " + user.toString());
return userManager.login(user,session);
}
}
实体类以及vo对象:
@Data
@Schema(description = "业务类型元数据表saveDto")
public class BasicElDataDto {
@Schema(description = "主键新增不传")
@TableId(value = "pk_id", type = IdType.AUTO)
private String pkId;
@Schema(description = "业务类型")
private String serviceType;
@Schema(description = "字段名称")
private String elName;
@Schema(description = "字段类型")
private String elType;
3. 注解说明
Swagger3的注解与Swagger2有所不同,以下是一些常用注解的对照表:
4. 访问Swagger UI
启动您的Spring Boot应用后,您可以通过以下地址访问Swagger UI:
http://localhost:8080/doc.html
http://localhost:8080/swagger-ui/index.html