首先就是我们项目中用的swagger2,编辑的时候已经升级到3.0.0了
有空尝试下。
然后至少要是个spring的项目,支持@configuration这个注解的版本,我们项目中用的spring4.1.0。
然后就是开开心心的码代码了
@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(
basePackages = {"com.dc.itil"} //swagger扫描的包
)
public class Swagger2 {
@Bean
ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
/*
"API Title",
"API Description",
"API Version",
"API terms of service",
"API Contact Email",
"API Licence Type",
"API License URL"); */
"ITIL3 API doc",
"",
"1.0",
"",
"",
"",
"" );
return apiInfo;
}
@Bean
public Docket customImplementation(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
}
写好了配置类,需要加入一个展示api的页面, swagger UI 这个很好用
看一下目录结构,放在webapp下面,当然我这个是个maven项目
之后就是在接口上加上你的api描述了
启动项目,访问 doc文件夹 ,这时候出来的只是swagger的页面 ,啥也没有
只需要在这里键入你的api数据地址就能找到。当然你也可以让他初始化的时候就显示,这样更方便。
修改index.html中的,换成自己的
window.swaggerUi = new SwaggerUi({
url: url,
这样就可以完美优雅的查看接口文档,你之前写的乱七八糟的接口命名也会清晰的暴露出来。
坑:
1. 首先就是我写完配置类Swagger2 .java 之后,访问doc是可以访问的 就是出不来接口文档,这个时候千万不能着急,仔细思考,我一看文档里面标题也没出来,我猜想是@configuration修饰的类没起作用,果然在扫描包路径中没有添加
2. 当点击try it out之后发现访问的路径不对,这时候我审查元素了那个按钮,发现baseURI有问题,这时候需要修改swagger-ui.js中的basepath为自己的项目后端接口路径
this.basePath = response.basePath + "/api"|| '';
总结一下,这个真的很好用,尤其是前后端分离的项目,再也不用给前端大姐写复杂接口文档了,再也不用为接口稳当改来改去费劲了