Swagger3基本使用

Swagger

课程目标

Swagger简介【了解】

Springboot整合swagger【掌握】

Swagger 常用注解【掌握】

knife4j-Swagger【会用】

一、Swagger3简介

	Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的⼀种交互式文档，客户端 SDK 的自 动生成等功能。

	Swagger 的目标是为 REST APIs  定义一个标准的、与语⾔言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。当服务通过 Swagger 定义，消费者就能与远程的服务互动通过少量的实现逻辑。Swagger（丝袜哥）是世界上最流行的 API 表达工具。

OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后，Swagger规范正式更名为OpenAPI规范，并且根据OpenAPI规范的版本号进行了更新。因此，Swagger 3.0对应的就是OpenAPI 3.0版本，它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比，Swagger 3.0更加强调对RESTful API的支持和规范化，提供了更丰富和灵活的定义方式，并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。

二、Springboot整合swagger3

	使用 Spring Boot 集成 Swagger 的理念是，使用用注解来标记出需要在 API 文档中展示的信息，Swagger  会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具，它提供了 API  管理的全套解决方案，API 文档管理需要考虑的因素基本都包含，这里将讲解最常用的定制内容。

• 添加依赖
  
  
  org.springdoc
  springdoc-openapi-starter-webmvc-ui
  2.6.0
  
  
  org.springdoc
  springdoc-openapi-starter-webmvc-api
  2.6.0
  

• 创建 SwaggerConfig 配置类
  /**
  * swagger3配置类
  */
  @Configuration
  public class SwaggerConfig {

      @Bean
      public OpenAPI openAPI(){
          return new OpenAPI().info(this.getInfo());
      }
  
      public Info getInfo(){
          return new Info()
                  .title("Springboot集成Swagger3") //标题
                  .description("Springboot集成Swagger3接口说明") //项目描述
                  .contact(new Contact().name("蜗牛学院")) //作者
                  .version("V1.0"); //版本号
  
      }
  }
  

• 访问swagger
  启动项目后输入：http://localhost:8080/swagger-ui/index.html 可看到swagger页面
  如果在访问 /swagger-ui/index.html 时出现 404 。这是因为，当你访问 .html 等静态资源时，Spring MVC 默认是在你自己项目的 resources/static 目录下去找它们，如果没有，自然就是 404 。而 swagger 相关的 .html 等静态资源是在依赖包含的 swagger-ui 项目（jar包） 下。所以，你需要通过静态资源配置来『告诉』Spring MVC 当收到 swagger 相关的静态资源访问时，去对应的这个目录下找它们。
  /**
  * spring mvc配置类
  */
  @Configuration //项目启动时加载此类
  public class WebMvcConfig implements WebMvcConfigurer {
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
  registry.addResourceHandler(“/swagger-ui/**”)
  .addResourceLocations(“classpath:/META-INF/resources/webjars/springfox-swagger-ui/”);
  }
  }

• 配置访问路径
  swagger的访问路径可以自己更改

  • 默认路径
    springdoc:
    api-docs:
    path: /v3/api-docs
    swagger-ui:
    path: /swagger-ui.html #可以改成自己喜欢的路径，如/doc.html

三、knife4j-Swagger

knife4j 是 Swagger 生成 API 文档的增强解决方案，最主要是 knife4j 提供了动态字段注释功能实现 Map 来接收参数这个的接口文档生成，忽略参数属性来实现同一个实体类对不同接口生成不同的文档

• 添加依赖
  前面swagger3的依赖不需要了
  
  
  com.github.xiaoymin
  knife4j-openapi3-jakarta-spring-boot-starter
  4.3.0
  

• 创建配置类
  /**
  * swagger3配置类
  */
  @Configuration
  public class SwaggerConfig {
  @Bean
  public OpenAPI openAPI(){
  return new OpenAPI().info(this.getInfo());
  }

      public Info getInfo(){
          return new Info()
                  .title("Springboot集成Swagger3") //标题
                  .description("Springboot集成Swagger3接口说明") //项目描述
                  .contact(new Contact().name("蜗牛学院")) //作者
                  .version("V1.0"); //版本号
      }
  }
  

  启动项目后通过：http://127.0.0.1:8080/doc.html 访问knife4j页面

四、Swagger3 常用注解

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息等。

1、@Tag

作用于类上，一般用来对controller类进行说明

语法：  
   @Tag(name = "用户接口", description = "用户管理相关接口")

示例 ：
@RestController
@Tag(name="用户操作")
public class UserController {
    
}

2、@Operation

作用于Controller的方法上。用于对controller方法进行说明

语法：
@Operation(
  summary = "操作摘要",
  description = "操作的详细描述",
  operationId = "operationId",
  tags = "tag1",
  parameters = {
    @Parameter(name = "param1", description = "参数1", required = true),
    @Parameter(name = "param2", description = "参数2", required = false)
  })
 
 示例 ：
 	@GetMapping("/user/list")
    @Operation(summary = "用户列表")
    public List<User> userList(){
        return userService.finUser();
    }

参数说明：

• summary：简短描述
• description ：更详细的描述
• hidden：是否隐藏
• tags：标签，用于分组API
• operationId：操作的唯一标识符，建议使用唯一且具有描述性的名称
• parameters：指定相关的请求参数，使用 @Parameter 注解来定义参数的详细属性。
• requestBody：指定请求的内容，使用 @RequestBody 注解來指定请求的类型。
• responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属性。

3、@Parameters

作用于Controller的方法上。@Parameters注解中包含多个 @Parameter 注解，通过@Parameter注解对controller方法中的非对象类型形参进行说明

语法：
@Parameters({
  @Parameter(
    name = "param1",
    description = "description",
    required = true,
    in = ParameterIn.PATH,
    schema = @Schema(type = "string")
  ),
  @Parameter(
    name = "param2",
    description = "description",
    required = true,
    in = ParameterIn.QUERY,
    schema = @Schema(type = "integer")
  )
})

示例：
	@GetMapping("/user/query")
    @Operation(summary = "根据条件查询用户")
    @Parameters({
            @Parameter(name="username",in= ParameterIn.QUERY,
                    description = "用户名",required = true,
                    schema = @Schema(type ="String")),
            @Parameter(name="age",in= ParameterIn.QUERY,
                    description = "年龄",required = true,
                    schema = @Schema(type ="Integer"))
    })
    public List<User> queryUser(@RequestParam(value = "username",required = true,defaultValue = "") String username,
                                @RequestParam(value = "age",required = true,defaultValue = "0") Integer age){
        return userService.finUser();
    }

@Parameter参数说明：

• name : 指定的参数名
• in：参数来源，可选 query、header、path 或 cookie，默认为空，表示忽略
• ParameterIn.QUERY 请求参数
• ParameterIn.PATH 路径参数
• ParameterIn.HEADER header参数
• ParameterIn.COOKIE cookie 参数
• description：参数描述
• required：是否必填，默认为 false
• schema ：参数的数据类型。如 schema = @Schema(type = “string”)

4、@ApiResponses

作用于Controller的方法上。@ApiResponses包含多个@ApiResponse。通过@ApiResponse对controller方法的返回值进行说明

语法：
@ApiResponse(responseCode = "200", description = "查询成功", 
content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "查询失败")


示例：
	@GetMapping("/user/query")
    @Operation(summary = "根据条件查询用户")
    @ApiResponses({
            @ApiResponse(responseCode = "2000",description = "多条件查询成功",
                    content = @Content(schema = @Schema(implementation = List.class))),
            @ApiResponse(responseCode = "5000",description = "多条件查询失败成功")
    })
    public ResponseResult<List<User>> queryUser(){
        return new ResponseResult<>(2000,"OK",null);
    }

@ApiResponse参数说明：

• responseCode：响应的 HTTP 状态码
• description：响应信息的描述
• content：响应的内容

5、@Schema

用于FO的类上。用于对controller中对象参数对应的FO对象的属性进行说明

• vo实体类
  @Data
  @Tag(name = “用户Vo”, description = “接收用户信息实体类”)
  public class UserVo implements Serializable {
  private static final long serialVersionUID = 1L;
  @Schema(name = “id”, type = “Integer”,description = “用户id”,defaultValue =“0”)
  private Integer id;
  @Schema(name = “username”, type = “String”,description = “用户真实姓名”,defaultValue = “”)
  private String username;
  @Schema(name = “birthday”, type = “LocalDateTime”,description = “生日”,defaultValue = “”)
  private LocalDateTime birthday;
  @Schema(name = “sex”, type = “String”,description = “性别”,defaultValue = “男”)
  private String sex;
  }
  参数说明：
  name：名称
  title：标题
  description：描述
  example：示例值
  required：是否为必须
  format：属性的格式。如 @Schema(format = “email”)
  maxLength 、 minLength：指定字符串属性的最大长度和最小长度
  maximum 、 minimum：指定数值属性的最大值和最小值
  pattern：指定属性的正则表达式模式
  type： 数据类型（integer，long，float，double，string，byte，binary，boolean，date，dateTime，password），必须是字符串。如 @Schema=(type=“integer”)
  implementation ：具体的实现类，可以是类本身，也可以是父类或实现的接口。
• controller
  @PostMapping(“/user/add”)
  @Operation(summary = “添加用户”)
  public ResponseResult<List> addUser(@RequestBody UserFo userFo){
  return new ResponseResult<>(2000,“OK”,null);
  }

五、spring security放行swagger3

修改security配置类

 /**
     * spring security过滤器链配配置
     * @param http
     * @return
     * @throws Exception
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception{
        //鉴权配置
        http.authorizeHttpRequests(authorizeHttpRequests->authorizeHttpRequests
                //允许所有的OPTIONS请求
                .requestMatchers(HttpMethod.OPTIONS,"/**").permitAll()
                //放行swagger3
                .requestMatchers(HttpMethod.GET,"/v3/api-docs/**","/doc.html","/webjars/**").permitAll()
                .anyRequest().authenticated());

        //认证配置
        http.formLogin()
                .successHandler(simpleAuthenticationSuccessHandler) //认证成功后的处理器
                .failureHandler(simpleAuthenticationFailureHandler) //认证失败后的处理器
                .permitAll();//这句配置很重要，新手容易忘记。放开 login.html和dologin 的访问权

        //退出操作配置
        http.logout().logoutSuccessHandler(simpLogoutSuccessHandler);

        //将自定义的jwtFilter添加到Spring Security过滤器链的倒数第二个以前
        http.addFilterAfter(jwtFilter, UsernamePasswordAuthenticationFilter.class);

        //认证和鉴权异常配置
        http.exceptionHandling()
                .authenticationEntryPoint(simpleAuthenticationEntryPoint) //认证异常处理器
                .accessDeniedHandler(simpleAccessDeniedHandler); //鉴权异常处理器

        //前后端项目中要禁用掉session
        http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
        //关闭crsf 跨域漏洞防御
        http.csrf(csrf-> csrf.disable());
        return http.build();
    }