springboot整合swagger

第一步：添加依赖

在pom文件中添加下面的依赖

	io.springfox
	springfox-swagger2
	2.9.2


	io.springfox
	springfox-swagger-ui
	2.9.2





	org.springframework.boot
	spring-boot-starter-web

第二步：配置Swagger

新建一个swagger配置文件，写入下面内容

import springfox.documentation.service.Contact;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.slm.tools.project.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("springboot整合Swagger")//swagger接口文档标题
                        .description("SpringBoot项目整合Swagger，代替手动维护的接口文档")//swagger接口文档描述
                        .version("1.0")//swagger接口文档版本
                        .contact(new Contact("Sun Luming","https://blog.csdn.net/sun_luming","[email protected]"))//文档作者信息
                        .license("Sun Luming")//文档许可证
                        .licenseUrl("https://blog.csdn.net/sun_luming")//文档许可证连接
                        .build());
    }
}

上面内容中的apis(RequestHandlerSelectors.basePackage(“com.slm.tools.project.controller”))部分是配置swagger要扫描的包，也就是你的项目的controller所在包

第三步：写一个测试Controller

@Api(tags = "测试swagger的Controller")
@RestController
@RequestMapping("test")
public class TestController {

    @GetMapping("test1")
    @ApiOperation("一个参数的请求")
    @ApiImplicitParam(name = "userId",value = "用户id",defaultValue = "1",required = true)
    public Map getTest(@RequestParam Integer userId){
        Map result = new HashMap<>();
        result.put("test","test");
        result.put("id",userId);
        result.put("msg","一个参数的请求");
        return result;
    }

    @GetMapping("test2")
    @ApiOperation("多个参数的请求")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId",value = "用户id",defaultValue = "16",required = true),
            @ApiImplicitParam(name = "name",value = "用户名",defaultValue = "张三")
    })
    public Map getTest(@RequestParam(required = true) Integer userId, @RequestParam String name){
        Map result = new HashMap<>();
        result.put("id",userId);
        result.put("name",name);
        result.put("msg","多个参数的请求");
        return result;
    }

}

swagger注解学习了解

@Api(tags = "测试swagger的Controller")

@Api用来描述概括一个controller的作用（如上图①）

@ApiOperation("一个参数的GET请求")

@ApiOperation用来描述一个接口方法的作用（如上图②）

@ApiImplicitParam(name = "id",value = "用户id",defaultValue = "1",required = true)

@ApiImplicitParam用来描述方法的一个参数，描述内容包括参数名、参数中文描述、参数默认值和参数是否必填（如上图③）

注意：

第一点：

@ApiImplicitParam注解内的defaultValue属性很好用，defaultValue属性用来给参数设置默认值，在调试参数比较多的接口时每次都要输入很多参数，这就很痛苦，但是当使用defaultValue设置默认值后，每次调试接口会自动填充这些参数，这就很舒服了

第二点：

@ApiImplicitParam注解内的required属性是用来描述参数是否必填（如上图④），但是这个必填只限于使用swagger调试接口，如果要真正指定这个参数是必填项，还要加上一个注解@RequestParam(required = true)（如上图⑥）

@ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",defaultValue = "16",required = true),
            @ApiImplicitParam(name = "name",value = "用户名",defaultValue = "张三")
})

@ApiImplicitParams注解用来包裹多个@ApiImplicitParam注解，也就是当接口有多个参数时要使用@ApiImplicitParams注解把这多个@ApiImplicitParam参数注解包裹起来使用。

第四步：启动项目，访问下面连接：

http://localhost:8080/swagger-ui.html

第五步：调用接口

在接口列表点击接口的地址展开接口：

点击“Try it out”按钮，根据提示输入参数：

参数输入后点击Execute按钮，可以看到Response body中已经有返回数据了。

目前就学习到这么多，后续有收获再补充。