本教程版本使用2.9.2
1、导入maven依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.5</version>
</dependency>
2、SwaggerConfig设置
import java.util.ArrayList;
import java.util.List;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter{
@Bean
public Docket swaggerSpringMvcPlugin() {
//添加head参数start
ParameterBuilder ticketPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
ticketPar.name("token").description("token")
.modelRef(new ModelRef("String")).parameterType("header")
.required(false).build();
pars.add(ticketPar.build());
//添加head参数end
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.apis(RequestHandlerSelectors.basePackage("com.enw"))
.build().globalOperationParameters(pars);
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("API接口文档")
.description("CRM管理系统API接口文档")
.contact(new Contact("", "", ""))
.version("1.0")
.build();
}
}
3、具体使用
@Api(tags="角色控制器")
@RestController
@RequestMapping("/role/")
public class RoleController extends BaseController {
@Autowired
private RoleService roleService;
@SuppressWarnings("unchecked")
@ApiOperation(value = "获取角色列表" , notes="获取角色列表")
@ApiImplicitParam(name = "role", value = "角色信息", required = false, dataType = "Role")
@PostMapping("list")
@UserLoginToken
public JsonResult<Role> roleList(@RequestBody Role role) {
List<Role> list = this.roleService.findAllRole(role);
return JsonResult.success(list);
}
}
4、访问 localhost:端口号/doc.html 效果如下:
注意:
1、如果有拦截器需要放开的路径:
"doc.html","/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**"
2、一般前后端分离,前端的token都是封装到请求头header中的,设置统一请求头token
//添加head参数start
ParameterBuilder ticketPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
ticketPar.name("token").description("token")
.modelRef(new ModelRef("String")).parameterType("header")
.required(false).build();
pars.add(ticketPar.build());
//添加head参数end
3、今天使用doc.html访问时后台报错:java.lang.NumberFormatException: For input string: "".原因是:
由于我pom引入的io.springfox:springfox-swagger-ui:2.9.2版本的jar包内置为io.swagger:swagger-models包为1.5.20版本。1.5.20版本中判断example只判断是否为null,没有判断example为空字符串""的情况所以报错.1.5.21版本新增了判断example是否为null和"".
解决办法:所以排除1.5.20包重新导入1.5.21包即可解决,具体依赖如下(标红部分注意):
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>