在Springboot整合Swagger时,想要使用官方的swagger-ui来实现文档中的接口排序并没有找到方法。所以使用了swagger-bootstrap-ui来实现该功能,swagger-bootstrap-ui能够实现Swagger-UI的增强。其中就有实现文档中接口排序的功能。其他功能请看swagger-bootstrap-ui开发指南
下面介绍实现步骤:
- 先引入swagger和swagger-bootstrap-ui的依赖
<!-- 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>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
由于在这使用了swagger-bootstrap-ui所以没有引入springfox-swagger-ui 。因为用swagger-bootstrap-ui已经可以生成文档UI界面了。
至于为什么要在springfox-swagger2中排除swagger-models依赖,而引入1.5.21版本的swagger-models的依赖请看上篇博客 Springboot–swagger2.9.2版本出现的NumberFormatException报错
- 配置Swagger2Config.java类,注意要加上注解@EnableSwaggerBootstrapUI,表示开启UI增强
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
// 只扫描类上有API注解的class
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
// 只扫描方法上有ApiOperation注解的方法
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.apis(RequestHandlerSelectors.basePackage("com.work.ohstudy.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfoBuilder()
.title("测试接口文档列表")
.description("该接口文档测试用")
.version("1.0")
.build());
}
}
- 在 Controller层使用注解,一般注解都和平时使用Swagger一样正常使用,只不过在这里要实现接口排序,所以要在接口上方增加个注解 @ApiOperationSort,或者在@ApiOperation注解中使用position属性,position的优先级大于@ApiOperationSort
(Swagger使用介绍,Swagger各个注解介绍)
测试用Controller,UserController.java
@Api(value = "用户接口列表",tags = {"用户接口列表"})
@RestController
public class UserController {
@Autowired
private TokenService tokenService;
@Autowired
private UserService userService;
@Autowired
private LogUntil logUntil;
@ApiOperationSort(2)
@RequestMapping(value = "/login",method = RequestMethod.POST)
@ApiOperation(value = "登录接口",notes = "登录成功返回token,若用户不存在则返回code码201,提示未注册")
@ApiImplicitParams({
@ApiImplicitParam(value = "用户openid",name = "openid",required = true,dataType = "String")
})
public RetResult login(String openid){
User user=userService.selectByopenid(openid);
if(user!=null) {
String s = tokenService.getToken(user.getId());
Map<String, Object> map = new HashMap<>();
map.put("token", s);
logUntil.insertlog("/login",user.getId(),"用户请求了登录接口");
return RetResponse.makeOKRsp(map);
}else{
return RetResponse.makeRsp(201,"账号未注册",null);
}
}
@RequestMapping(value = "/verify",method = RequestMethod.POST)
@ApiOperationSort(1)
@ApiOperation(value = "验证用",notes = "单纯作验证用")
@ApiImplicitParams({
@ApiImplicitParam(value = "用户openid",name = "openid",required = true,dataType = "String")
})
public String verify(){
System.out.println(TokenUntil.getTokenUserId());
return "已经通过验证";
}
}
- 输入localhost:端口号/doc.html访问文档页面,在文档页面设置中,打开增强,如下图所示
然后可以看到排序结果:
至此实现了Swagger接口文档中的接口排序功能
最后发现swagger-bootstrap-ui的作者在最新的版本中把该项目进行了更名,该项目被更名为Knife4j,因为我的问题使用swagger-bootstrap-ui的简单增强功能已经解决,所以没使用最新的Knife4j,读者如果对最新版本有兴趣的话可以去Gitee:Knife4j查看文档。