Swagger学习笔记

关于Swagger注解的一些参数可以看这位作者的总结

<!--        swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!--        第一种界面,启动后访问http://localhost:9090/swagger-ui.html#/-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui
         第二种界面,启动后访问http://localhost:9090/doc.html/-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.9</version>
        </dependency>

注解

(1) Swagger2请求类注解
1.@API :
标识Swagger识别的类
放在@Controller注解并列的请求类
核心参数value,tags,desrciption

(2) Swagger2请求方法注解
1.@ApiOperation:
标识Swagger识别的方法
2. @ApiImplicitParam：
标识方法的参数的说明
3. @ApiResponse：
标识方法返回值的说明

(3) Swagger2对象类注解
1.@ApiModel:
标识Swagger识别的JavaBean,放在JavaBean的类定义上
2.@ApiModelProperty:
标识JavaBean的属性

(4) 总结图:

自己写的demo

1.默认配置下:

@SpringBootApplication
@MapperScan("com.xzit.syk.mapper")
@EnableSwagger2
public class MallApplication {

    public static void main(String[] args) {
        SpringApplication.run(MallApplication.class, args);
    }

}

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

报这个错,可能需要在yml中更改springmvc的配置

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

/**
 * @author by ShiYunKai
 * @date 2022/11/23
 */

@Api(tags = "用户接口")
@RestController
@RequestMapping("/sysUser")
public class SysUserController {

    @Resource
    private SysUserService sysUserService;

    @GetMapping("findAll")
    public Result findAll(){
        return Result.success(sysUserService.list());
    }

    @ApiOperation(value = "用户登录的业务逻辑",notes = "根据用户账户查询用户信息,返回1个用户对象说明登录成功")
    @ApiResponses(value = {
            @ApiResponse(code = 200,message = "Success|Ok"),
            @ApiResponse(code = 401,message = "not authorized!"),
            @ApiResponse(code = 403,message = "forbidden!!!"),
            @ApiResponse(code = 404,message = "not found!!!")
    })
    /**
     *   @ApiImplicitParam(name = "userid", value = "用户id", paramType = "Integer"),用于标识传入的参数信息
     *    比如说 XXX(@RequestParam(value = "pid") Integer pid)
     */
    @PostMapping("/login")
    public Result login(@RequestBody SysUser sysUser){
        return Result.success(sysUserService.login(sysUser));
    }
}

/**
 * @author by ShiYunKai
 * @date 2022/11/23
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "用户实体类",value = "用户对象")
public class SysUser {
    @ApiModelProperty(value = "编号")
    private Integer id;
    @ApiModelProperty(value = "账号")
    private String account;
    @ApiModelProperty(value = "密码")
    private String password;
    @ApiModelProperty(value = "手机号")
    private String phone;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
    @ApiModelProperty(value = "创建时间")
    private LocalDateTime createtime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
    @ApiModelProperty(value = "更改时间")
    private LocalDateTime updatetime;
}

访问地址:http://localhost:9090/swagger-ui.html#/

2.自定义Swagger的配置

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
//多环境配置下需要开启这个注解
//@Profile({"dev","test","prod"})
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                //注意:如果再想设置一个组的话，就需要在配置一个 Docket docket()的方法,即一个组对应一整个这样的 docket()方法
                .groupName("sysUserAPI")//如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
                // 配置基本信息
                .apiInfo(apiInfo())
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                                //.any() // 扫描全部的接口，默认
                                //.none() // 全部不扫描
                                .basePackage("com.xzit.syk.controller") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
                )
                .paths(PathSelectors
                                .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();

    }


    /**
     * 第二个组
     * @return
     */
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("sysFileAPI")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors
                                .basePackage("com.xzit.syk.controller")
                )
                .paths(PathSelectors
                                .any()
                )
                .build();

    }

    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "CloudNET_Syk","www.baidu.com","xxx@qq.com");
        return new ApiInfoBuilder()
                .title("测试的接口文档") // 标题
                .description("swaggerAPI接口文档的测试") // 描述
                .version("1.0") // 版本
                .contact(contact)
                .build();
    }



}

注意点

尽量使用@ApiParam注解代替@ApiImplicitParams注解分装参数