springboot 集成 swagger

前提：创建好spring boot 项目。并包含 spring-boot-starter-web 依赖

1，添加 swagger 依赖

<!--swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

2，创建 swagger 配置类

package com.june.servicebase;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.google.common.base.Predicates;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration//配置类
@EnableSwagger2 //swagger注解
public class SwaggerConfig {

	@Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*"))) //包含路径时不显示
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();        
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("这是ApiInfo的title")
                .description("这是ApiInfo的description")
                .version("这是ApiInfo的version")
                .contact(new Contact("june", "http://june.com", "june@qq.com"))
                .build();
    }
}

到此已经集成swagger结束了。 当你写好controller类中的请求后，启动项目，访问http://localhost:8080/swagger-ui.html (改成自己的 IP 和 端口号) ，就可以看到 swagger 接口文档界面了。写好的controller的方法的请求都会看到

---

---

举个栗子（ Controller 控制器类）

@Api(description = "讲师管理")
@CrossOrigin
@RestController
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

	@Autowired
	private EduTeacherService teacherService;
	
	@ApiOperation(value = "添加讲师")
	@PostMapping("addTeacher")
	public R addTeacher(@RequestBody EduTeacher eduTeacher) {
		boolean save = teacherService.save(eduTeacher);
		if (save) {
			return R.ok();
		} else {
			return R.error();
		}
	}
}

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

添加请求参数

在很多时候，我们需要在调用我们每一个接口的时候都携带上一些通用参数，比如采取token验证逻辑的往往在接口请求时需要把token也一起传入后台

修改SwaggerConfig配置类，替换成如下内容，利用ParameterBuilder构成请求参数。

package com.june.servicebase;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.google.common.base.Predicates;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration//配置类
@EnableSwagger2 //swagger注解
public class SwaggerConfig {

	@Bean
    public Docket webApiConfig(){
    	
    	// ======= 添加部分 开始  ======= 
     	ParameterBuilder parameterBuilder = new ParameterBuilder();  
        List<Parameter> parameters = new ArrayList<Parameter>();  
        parameterBuilder.name("token").description("令牌")
                                      .modelRef(new ModelRef("string"))
                                      .parameterType("header")
                                      .required(false)
                                      .build();  
        parameters.add(parameterBuilder.build());
        // ======= 添加部分 结束  ======= 
        
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*"))) //包含路径时不显示
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .globalOperationParameters(parameters);  // ======添加部分======   
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("这是ApiInfo的title")
                .description("这是ApiInfo的description")
                .version("这是ApiInfo的version")
                .contact(new Contact("june", "http://june.com", "june@qq.com"))
                .build();
    }
}

常用注解说明. swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。

@Api: 修饰整个类，用于controller类上

@ApiOperation: 描述一个接口，用户controller方法上

@ApiParam: 单个参数描述

@ApiModel: 用来对象接收参数,即返回对象

@ApiModelProperty: 对象接收参数时，描述对象的字段

@ApiResponse: Http响应其中的描述，在ApiResonse中

@ApiResponses: Http响应所有的描述，用在

@ApiIgnore: 忽略这个API

@ApiError: 发生错误的返回信息

@ApiImplicitParam: 一个请求参数

@ApiImplicitParam: 多个请求参数