SpringBoot项目集成Swagger2

亦凉 2024-04-01 11:28 90阅读 0赞

### 前言 ###

使用swagger2编写接口文档方便快捷，swagger2是为了方便前后端分离项目的交互，后端可以用来编写字段的描述，方便前端在对接口的了解每个字段的含义，不会把字段搞混，减轻前后端交互的压力，提高开发效率。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

常用注解

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

*  @Api：修饰整个类，放在类上面，描述Controller的作用
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口，放在方法或接口上
 *  @ApiParam：单个参数描述

- 用法：@RequestParam(value ="currPageNo", defaultValue = "1") Integer currPageNo,
           @RequestParam(value ="pageSize", defaultValue = "10") Integer pageSize,
           @RequestParam(value ="orderNo",required = false) @ApiParam("订单编号") String orderNo

*  @ApiModel：用对象来接收参数，放在类上面
 *  @ApiModelProperty：用对象接收参数时，描述对象的一个字段，放在字段上面
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数

### 1、添加相关依赖 ###

<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>
        
        
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>25.1-jre</version>
        </dependency>

### 2、创建相关工具类 ###

/**
    
     * @Author zzw
    
     * @Create
    
     * @Description
    */
       @Configuration
       @EnableSwagger2
       @EnableSwaggerBootstrapUI
       public class Swagger2Config {
        
    
       @Bean
       public Docket createRestApi() {
        
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   // 下面的包名为项目controller所在包
                   .apis(RequestHandlerSelectors.basePackage("me.zhyd.justauth"))
                   .paths(PathSelectors.any())
                   .build()
                   .securityContexts(securityContexts())
                   // 通过Swagger2的securitySchemes配置全局参数
                   .securitySchemes(securitySchemes());
       }
    
       private ApiInfo apiInfo() {
        
           return new ApiInfoBuilder()
                   .title("页面标题")
                   .description("描述")
                   .contact(new Contact("zzw", "http:IP:端口号/doc.html", "@qq.com"))
                   .version("版本")
                   .build();
       }
    
       private List<ApiKey> securitySchemes() {
        
           // 设置请求头信息
           List<ApiKey> result = new ArrayList<>();
           // 参数一name为参数名，参数二keyname为参数key，参数三passAs为参数存放位置，其值有header、query、path等，其中
           // header为请求头，query为请求参数，path为请求路径
           ApiKey apiKey = new ApiKey("Authorization", "Authorization", "Header");
           result.add(apiKey);
           return result;
       }
    
       // 在Swagger2的securityContexts中通过正则表达式，设置需要或不需要使用参数的接口
       private List<SecurityContext> securityContexts() {
        
           List<SecurityContext> result = new ArrayList<>();
           // 调用下面定义的getContextByPath()，设置需要登录认证的路径，比如此处的/hello/.*
           result.add(getContextByPath("/hello/.*"));
           // 上面配置后，在Swagger文档中访问/hello路径时，需要用到securitySchemes()方法中配置的全局参数
           return result;
       }
       private SecurityContext getContextByPath(String pathRegex) {
        
           return SecurityContext.builder()
                   .securityReferences(defaultAuth())
                   .forPaths(PathSelectors.regex(pathRegex))
                   .build();
       }
       private List<SecurityReference> defaultAuth() {
        
           List<SecurityReference> result = new ArrayList<>();
           // AuthorizationScope权限范围对象，其参数一scope为权限范围名称，global表示全局，其参数二为范围范围描述
           AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
           AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
           authorizationScopes[0] = authorizationScope;
           result.add(new SecurityReference("Authorization",authorizationScopes));
           return result;
       }
    
    }

### 3、添加配置 ###

解决swagger2启动错误：Cannot invoke “org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.toString()” because the return value of “springfox.documentation.spi.service.contexts.Orderings.patternsCondition(springfox.documentation.RequestHandler)” is null

添加配置( \# 解决swagger2的错误问题)

application.properties文件配置

spring.mvc.pathmatch.matching-strategy = ant-path-matcher

application.yml文件配置

spring:
      mvc:
        pathmatch:
          matching-strategy: ant-path-matcher

### 4、启动项目 ###

使用 http:IP:端口号/doc.html 或者 http:IP:端口号/swagger-ui.html 进行访问

![在这里插入图片描述][65d2b88ded104da78d92adca02b0b7ce.png]

![\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-pyAYoPDZ-1666855270203)(C:\\Users\\Administrator\\AppData\\Roaming\\Typora\\typora-user-images\\image-20221027145730114.png)\]][img-pyAYoPDZ-1666855270203_C_Users_Administrator_AppData_Roaming_Typora_typora-user-images_image-20221027145730114.png]至此swagger2就集成完毕了。

[65d2b88ded104da78d92adca02b0b7ce.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/01/68853c80ffab428cad74400951045ac3.png
[img-pyAYoPDZ-1666855270203_C_Users_Administrator_AppData_Roaming_Typora_typora-user-images_image-20221027145730114.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/01/b60ce2f84a554b689549825f28d01098.png