SpringBoot集成Swagger2在线文档
前言
在开发RestFul接口时,我们常常需要自己写一 接口文档,同时还要测试,很麻烦.
使用Swagger2集成,可以直接生成在线文档,同时还能直接测试,非常方便.
1.引入Swagger2的pom依赖
<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.添加Swagger2配置
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;
/**
* Created by zengchao on 2018/6/6.
*/
@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();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("用户库需求API文档")
//创建人
.contact(new Contact("JAVA组", "", ""))
//版本号
.version("1.0")
//描述
.description("此为用户库需求文档")
.build();
}
}
注意:该文件放在你的XXXApplication.java类的同级目录下
3.配置资源映射
默认情况下,上面两步完成,访问http://localhost:8080/swagger-ui.html就可以正常访问了.
但是,可能有的人的对静态资源做了自己的映射.根据自己情况配置.下面 是我自己的配置代码.
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
/**
* Created by zengchao on 2018/6/14.
*/
@Configuration
public class WebConf extends WebMvcConfigurationSupport {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//将所有/static/** 访问都映射到classpath:/static/ 目录下
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
//swagger2
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
super.addResourceHandlers(registry);
}
}
最重要的就是下面两句
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
值得注意的是,我使用的是SpringBoot 2.x的版本,继承的是WebMvcConfigurationSupport,但是使用1.5X的版本,继承的是*WebMvcConfigurerAdapter,
4.接口添加注解自动生成在线API文档
在Controller类上添加注解
@Api(description = "用户相关接口")
@CrossOrigin
接口方法上添加注解
@ApiOperation(value = "1-查询用户")
实体bean上
@ApiModel
实体bean属性上
@ApiModelProperty(value = "收货手机号/昵称/用户ID")
这只是一部分注解,还有很多注解.如需了解更多,请自行搜索.
5.效果图
总体效果图
具体接口效果图
