springboot集成swagger2以及使用

springBoot 集成swagger2

1、首先在pom文件中添加swagger2的相关依赖：

<!-- swagger2 配置  用户生成文档-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<!-- 默认网页ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

2、添加swagger相关的依赖

@Configuration //使spring管理
@EnableSwagger2 //开启swagger配置
public class Swagger2 {

//    http://localhost:8088/swagger-ui.html    原路径
//   http://localhost:8088/doc.html    新皮肤路径

	// 配置swagger2核心配置 docket
	@Bean
	public Docket createRestApi() {
	    return new Docket(DocumentationType.SWAGGER_2) //指定api类型为swagger2
	                .apiInfo(apiInfo())                //用于定义api文档汇总信息
	                .select()
	                .apis(RequestHandlerSelectors
	                        .basePackage("com.imooc.controller"))  //指定controller包
	                .paths(PathSelectors.any())           //所有controller
	                .build();
	}
	
	private ApiInfo apiInfo(){
	    return new ApiInfoBuilder()
	                .title("***平台接口api")    //文档页标题
	                .contact(new Contact("su丶因陀罗",    //联系人信息  姓名  博客地址  邮箱
	                        "https://me.csdn.net/qq_36990033",
	                        "****@qq.com"))
	                .description("***平台接口文档")   //详细信息
	                .version("1.0.1")     //文档版本号
	                .termsOfServiceUrl("https://me.csdn.net/qq_36990033")  //网站地址
	                .build();
}

3、到此为止就可以生产文档咯，访问上面的原地址可以观看文档；
不过swagger2自带的文档样式看着不太习惯。我们可以引入另外的一个第三方的ui来改变页面样式，在pom文件中引入：

<!-- 集成的新样式ui -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.6</version>
        </dependency>

访问上方的新皮肤路径就可以观看了。

4、swagger2文档生成的时候全是英文没有注释的，看起来非常不方便；
我们可以通过注解改变他的显示；

1）
在controller上加入@ApiIgnore 可以在生成文档时忽视此controller

@ApiIgnore //swagger2 生成文档的时候忽略此注解下的controller
@RestController
public class HelloController {

2）
在controller上加入@Api注解可以指定文档中接口类的名称 – 就是一级彩带的名称

@Api(value = "注册登录", tags = {"用于注册登录相关的接口"}) //swagger2 生成文档时的注释显示 类的
@RestController
@RequestMapping("passport")
public class PassportController {

3）
在controller中的方法上加入 @ApiOperation注解可以指定接口的注释

@ApiOperation(value = "用户名是否存在", notes = "用户名是否存在", httpMethod = "GET") //swagger2 生成文档时的注释显示   方法的
    @GetMapping("/usernameIsExist")
    public IMOOCJSONResult usernameIsExist(@RequestParam String username) {

4）
在封装的entity上加入@ApiModel注解可以指定生成文档中参数里面这个对象的所要显示的信息

@ApiModel(value = "用户对象BO", description = "从客户端，由用户串入的数据封装在此entity中")
public class UserBO {

5）
在属性上加入@ApiModelProperty可以指定生成的文档参数里面对象下各个属性所要显示的信息

 @ApiModelProperty(value = "用户名", name="username", example = "imooc", required = true)
    private String username;