SpringBoot整合Swagger3.0与常用注解

• 一.整合SpringBoot
• 二.Swagger常用注解说明
• • 2.1 控制类中的注解
  • 2.2 返回实体类和参数实体类注解
• 三.Swagger-Ui插件

SpringBoot整合Swagger3.0有很多需要注意的细节,一直在出问题,借鉴了很多人的,特此记录。

访问路径：http://localhost:8080/swagger-ui/index.html

Swagger3.0依赖导入(这个依赖可以代替另外两个，更好的与SpringBoot整合)

     
            io.springfox
            springfox-boot-starter
            3.0.0
        

接下来就是需要配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket getDocket(){

        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("<<互联商城>>后端接口说明")
                .description("此文档详细说明了后端接口规范")
                .version("v 1.0.0")
                .contact(new Contact("Mordle","https://blog.csdn.net/fhuqw?spm=1010.2135.3001.5343","zhanglei405@icloud.com"));
        ApiInfo info = apiInfoBuilder.build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)//指定文档风格
                .apiInfo(info)//指定生成文档中的封面信息，文档的标题、作者、版本
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mordle.mall.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

启动项会报空指针异常

错误原因：SpringBoot2.6.x使用PathPatternMatcher匹配路径，Swagger引用的Springfox基于AntPathMatcher匹配路径。匹配方式不同，导致错误。

解决思路：将SpringBoot的匹配路径方式更改为AntPathMatcher，两者相同即可。添加配置信息如下：

注意：配置文件可以写成.properties或者.yaml，但不能是.yml(不知道为啥)

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

此时访问会报404找不到页面，原因是mvc拦截，需要另外配置

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/swagger-ui/").setViewName("/swagger-ui/index.html");
    }
}

@Api 类注解,在控制类添加此注解,可以对控制器类进行功能说明

@ApiOperation 方法注解：说明接口方法的作用

@ApiImplicitParams和@ApiImplicitParam 方法注解,说明接口方法的参数

@ApiIgnore 方法注解,接口不会在ui文档中出现

@RestController
@RequestMapping("/user")
@Api(value = "提供用户的登录和注册接口",tags = "用户管理")
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation("用户登录接口")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
            @ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "111111")
    })
    @GetMapping("/login")
    public ResultVO login(@RequestParam("username") String name,@RequestParam(value = "password",defaultValue = "111111") String pwd){
        return userService.checkLogin(name,pwd);
    }
}

@ApiModel 类注解,在返回和参数实体类添加此注解,可以对返回和参数实体类进行说明

@ApiModelProperty 参数注解

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "响应的VO对象",description = "封装接口返回给前端的数据")
public class ResultVO {
    //响应给前端的状态码
    @ApiModelProperty(value = "响应状态码",dataType = "int")
    private int code;
    //响应给前端的信息
    @ApiModelProperty(value = "响应信息",dataType = "String")
    private String msg;
    //响应给前端的数据
    @ApiModelProperty(value = "响应数据",dataType = "Object")
    private Object data;
}

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "用户/买家信息")
public class User {

  	@ApiModelProperty(dataType ="int",required = false,value = "用户id")
    private String id;
    @ApiModelProperty(dataType = "String",required = true,value = "用户注册账号")
    private  String name;
    @ApiModelProperty(dataType = "String",required = true,value = "用户注册密码")
    private  String pwd;
}

访问地址：http://localhost:8080/doc.html

导入依赖

    com.github.xiaoymin
    swagger-bootstrap-ui
    1.9.6