springboot3升级之Swagger

作者: adm 分类: java 发布时间: 2024-04-27

swagger简介
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。它是一个开源的框架,提供了完整的解决方案,用于构建、设计、文档和调用RESTful Web服务。Swagger可以让开发人员快速创建API文档,并支持自动生成客户端和服务端代码。它还提供了强大的功能,如API的发现、定义、测试和可视化等。

Swagger通过注解来自动生成API文档,使得开发人员可以专注于编写代码,而不需要手动编写大量的文档。此外,Swagger还支持多种语言和框架,如Java、Spring等,可以方便地集成到现有的项目中。

总之,Swagger是一个强大的工具,可以帮助开发人员快速构建和文档化RESTful风格的Web服务。

配置依赖
依赖引入
此处使用的 swagger3 所用的依赖是:

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
     <version>2.2.15 </version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
     <version>2.1.0 </version>
</dependency>

由于使用的springboot是3.2.0版本,导致无法使用 swagger2 依赖无法使用:

曾经(2.9.2版本也测试过了,用不了):

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
       <version>3.0.0 </version>
</dependency>

Controller层配置

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
 
 
@RestController
public class HelloController {
 
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

打开网址为:

Swagger UI http://www.localhost:8080/swagger-ui/index.html

完成样式:

注解的变化

@Api(tags = "")     
改为     
@Tag(name = "")
 
@ApiModel(value="", description="")     
改为    
@Schema(name="", description="")
 
@ApiModelProperty(value = "", required = false)     
改为    
@Schema(name= "", description = "", required = false)
 
@ApiOperation(value = "", notes = "")    
改为    
@Operation(summary = "", description = "")
 
@ApiParam    改为     @Parameter
 
@ApiResponse(code = , message = "")  
改为
@ApiResponse(responseCode = "", description = "")

原注解释意:

一些常常用的注解:

@Tag
描述:用于给 API 分组,用途类似于为 API 文档添加标签。
可用于:方法、类、接口。
属性:name:分组的名称。
@Operation
描述:用于描述 API 的操作。
可用于:方法。
属性:
summary:操作的摘要信息。
description:操作的详细描述。
tags:指定 @Tag 注解的对象数组,用于将操作归类到特定的分组。
parameters:指定 @Parameter 注解的对象数组,用于描述操作的输入参数。
responses:指定 @ApiResponse 注解的对象数组,用于描述操作的响应结果。
requestBody:指定 @RequestBody 注解的对象,用于描述操作的请求体。
@Parameter
描述:用于描述操作的输入参数。
可用于:方法。
属性:
name:参数的名称。
in:参数的位置,可以是 path、query、header、cookie 中的一种。
description:参数的描述。
required:参数是否必需,默认为 false。
schema:指定 @Schema 注解的对象,用于描述参数的数据类型。
@ApiResponse
描述:用于描述操作的响应结果。
可用于:方法。
属性:
responseCode:响应的状态码。
description:响应的描述。
content:指定 @Content 注解的对象数组,用于描述响应的内容。
这个swagger3而不是swagger2

首先swagger3展示的信息比swagger2要详细。

其次swagger3 配置比较方便只需要一个依赖,而swagger2需要有依赖

,以及config的配置文件同时需要@Configuation去注入,还需要@EnableSwagger2注解去启动,以及内容还需要写相关的@Bean才可以使用。

还有一点是这个项目完整的开发完了,这个帮助文档是要删除的不然会有一定的安全问题,swagger2这配置这么多,可能会在删除的时候有遗漏等。

最后就是swgagger2与springboot3有版本不兼容等问题,所以不推荐使用。

以下就是swagger2使用时需要的相关配置:

@EnableSwagger2
@Configuration
public class SwaggerConfig {
 
    @Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("平台接口 v1.0")
                .description("平台接口")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

另外测试了一下那个spring scurity会不会拦截:

答案是:不登录会被拦截,登录了就可以进去,不需要重新输入用户名和密码。

如果觉得我的文章对您有用,请随意赞赏。您的支持将鼓励我继续创作!