Swagger3.0.0(springboot3.2.0)

swagger参考网址：

官网：OpenAPI Design & Documentation Tools | Swaggerhttps://swagger.io/tools/

mvnrepository.swagger3:Maven Repository: io.swagger.core.v3 » swagger-annotations (mvnrepository.com)https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotationsmvnrepository.swagger2 和 swagger UI：Maven Repository: springfox (mvnrepository.com)https://mvnrepository.com/search?q=springfox

注解详细解释：

Swagger 3 注解使用指南_swagger3 注解-CSDN博客https://blog.csdn.net/qq_52774158/article/details/131081371?spm=1001.2014.3001.5506

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 (www.localhost)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会不会拦截：

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