SpringBoot整合swagger2.9.2

                           SpringBoot整合swagger2.9.2

一、swagger介绍

1、背景

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。

2、介绍

swagger是一款让你更好的书写API文档的规范且完整框架。

swagger提供描述、生产、消费和可视化RESTful Web Service。

swagger是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二、springBoot整合swagger

1、maven依赖

<!-- swagger支持 -->
         <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>

2、config配置

@Configuration
@EnableSwagger2
public class SwaggerConfig{
	
	// swagger显示标识符在不同环境配置不同参数(测试环境开放,正式环境关闭保证安全)
	@Value("${spring.swagger.enableSwagger}")
	private boolean enableSwagger;
	
	@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .select()
                //controller接口项目地址
                .apis(RequestHandlerSelectors.basePackage("com.xx.xx.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("标题信息")
                .description("描述信息")
                .version("1.0")
                .build();
    }
}

3、注解使用

// 应用在控制层
@Api(value="controler介绍",tags={"controler介绍"})
@ApiOperation(value = "方法介绍", notes = "方法介绍")
@ApiImplicitParams @ApiImplicitParam 结合使用 方法参数介绍
@ApiParam类似于上面两个注解(推荐使用)

//应用于实体类
@ApiModel(description = "实体类介绍")
@ApiModelProperty(value = "属性介绍")

@RestController
@Slf4j
@Api(value="用户controller",tags={"用户操作接口"})
public class StudyController {
	@ApiOperation(value = "添加单个题库", notes = "添加单个题库")
	@PostMapping("/addQuestionBanks")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "userId", value = "用户ID", required = true,dataType = "int", paramType = "query"),
		@ApiImplicitParam(name = "userName", value = "用户实体user", required = true,dataType = "String", paramType = "query")
	})
	public String addQuestionBanks(@RequestParam Integer userId, @RequestParam String userName){
		return "success"+userId+userName;
	}

    @ApiOperation(value = "添加单个题库", notes = "添加单个题库")
	@PostMapping("/addQuestionBanks3")
	public String addQuestionBanks3(@ApiParam(value = "用户id", required = true) @RequestParam String[] arr, @ApiParam(value = "用户id", required = true) @RequestParam Long id){
		return null;
	}
}

@Data
@ApiModel(description = "参数")
public class ApiParamsReg implements Serializable{
	@ApiModelProperty(value = "用户id",example = "1")
    private Integer userId;
}

4、访问

http://服务地址:端口号/swagger-ui.html

5、注意事项

异常分析：Illegal DefaultValue null for parameter type integer`和`NumberFormatException: For input string: ""

参见博客：https://www.cnblogs.com/ampl/p/11426687.html

<!-- swagger支持 -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.9.2</version>
		    <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.9.2</version>
		</dependency>
		<dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>