做java Web的后端开发已经两年多了，一般都是开发完了接口，都把接口更新到wiki文档上，然后通知前端去文档上去查阅接口的详细描述， 当时经常接口会有变动，加参数或返回值夹字段，所以维护语线上一致的文档是一件非常麻烦的事情，前一段时间同事聊天说他们公司用的swagger2，这个不需要写文档，它是自动生成文档，只要会使用它提供的几个的注解就行，于是上网找了下资料，发现它于spring boot集成也非常方便。不废话直接看了代码。
首先，在maven项目的pom.xml加上他需要的依赖。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.5.0</version> </dependency>
然后在Application.class的同一目录,建立一个类名为Swagger2，类如下：
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
.paths(PathSelectors.any())
.build().useDefaultResponseMessages(false);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("微信API服务").description("wechat service").termsOfServiceUrl("no terms of service")
.version("1.0").build();
}
}
然后，在Swagger2类的同一级建立一个类名为WebMvcConfig类，代码如下：
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
这是为了让 spring boot加载处理swagger的资源的。
然后启动Application.class启动spring boot工程，直接访问http://localhost:8080/swagger-ui.html，就可以出现REST风格的api文档。
是不是很简单。
这其中自己也出现过问题，就是我的工程中是在拦截器中做了统一的权限验证，所以它一直都没有出现错误如下：
调试发现是在token验证时把Swagger2的访问页面的url给拦截了，也花费了自己的一点时间出解决，解决思路是在拦截其中，将url进行特殊判断，
让它通过，参考代码如下：
然后，重启应用，重新访问就出现了，在线的 Api文档就出现了。
接下来就是熟悉下 swagger2的几个注解的使用，如下
@Api:注解controller，value为@RequestMapping路径
@ApiOperation:注解方法，value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false
@ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名，value为注释，defaultValue设置默认 值,allowableValues设置范围值,required设置参数是否必须，默认为false
@ApiModel:注解Model
@ApiModelProperty:注解Model下的属性，当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value
@ApiIgnore:注解类、参数、方法，注解后将不在Swagger UI中显示。
到此借宿，是不是很简单。大家快去尝试下吧。