前后端分离后,api接口文档的维护就成了一个让人头疼的问题,api接口更新慢,或因开发工作量大,没时间整理文档,导致前后端分离后前端同学和后端同学都纠结于文档的问题。而swagger的出现,不亚于一道曙光,功能强大,ui简洁美观,提供在线测试,不能说完美,但基本上解决了文档的问题
本此搭建是基于springBoot项目,希望对大家有帮助
官方网站为:http://swagger.io/
步骤1.maven
在maven的pom文件中引入相关的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
步骤2.配置Swagger的配置文件
import java.util.ArrayList;
import java.util.List;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.service.Parameter;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("token").description("令牌")
.modelRef(new ModelRef("string")).parameterType("query").required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.sst"))
.paths(PathSelectors.any())
.build().globalOperationParameters(pars) ;
}
@SuppressWarnings("deprecation")
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("个人测试")
.description("个人测试用api")
.termsOfServiceUrl("http://blog.csdn.net/penyoudi1")
.contact("测试")
.version("1.0")
.build();
}
}
步骤3.在Controller中引入注解
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
@RestController
@RequestMapping("test")
@Api(value="测试接口Controller")
public class TestController {
@ApiOperation(value="测试用接口", notes="测试用接口" ,httpMethod="POST")
@ApiImplicitParams({
@ApiImplicitParam(name="name", value="用户姓名", dataType = "String", required=true, paramType="form"),
@ApiImplicitParam(name="id", value="id", dataType = "int", required=false, paramType="form")
})
@RequestMapping("word")
public String HelloWord(String name,Integer id) {
return "Hello Word";
}
}
然后输入地址 http://127.0.0.1:8080/SpringSwaggerTest/swagger-ui.html
可以查看到
看到这个页面,说明配置成功!!
以上就是swagger基于springBoot的配置方法,下面详细说一下具体的参数
swagger配置文件说明
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("token").description("令牌")
.modelRef(new ModelRef("string")).parameterType("query").required(false).build();
pars.add(tokenPar.build());
这段代码是默认参数,添加上后,所有的接口都会有一个公共参数,不需要在每个接口单独配置
.apis(RequestHandlerSelectors.basePackage("com.sst"))
这个是基于基于注解扫描的位置,写到目录最外层即可
return new ApiInfoBuilder()
.title("个人测试")
.description("个人测试用api")
.termsOfServiceUrl("http://blog.csdn.net/penyoudi1")
.contact("测试")
.version("1.0")
.build();
}
这个是一些页面展示数据的配置,用于标题,分组说明等
controller注解说明
@Api(value="测试接口Controller")
这个注解用于整个类上,对整个类中的接口列表进行简单说明
@ApiOperation(value="测试用接口", notes="测试用接口" ,httpMethod="POST")
value 和notes都是对接口的说明,是显示的位置不一样
httpMethod 是接口的提交方法,如果不写的话swagger会把所有的提交方式都展示一遍就像这样
@ApiImplicitParams({
@ApiImplicitParam(name="name", value="用户姓名", dataType = "String", required=true, paramType="form"),
@ApiImplicitParam(name="id", value="id", dataType = "int", required=false, paramType="form")
})
@ApiImplicitParams是传入参数的集合,里面可以包含多个参数
@ApiImplicitParam(name="name", value="用户姓名", dataType = "String", required=true, paramType="form"),
name是参数的名称,value是参数的说明,dataType是参数的类型,前端不是限制,仅做说明使用,required true时是必传参数,false是选填参数。paramType是提交方式=-= 好像都是写的from
以上就是基本的使用的参数说明
问题
1.在开发中遇到过,使用swagger做excel导出中文乱码的问题,尚未解决,如果你也遇到了,可以单独访问下接口,尝试下是否是swagger本身的问题
补充:
在实际开发中遇到过两个问题都已经处理,希望给其他同学提供帮助
1.当传入的参数用对象接的时候,swagger会将对象中的信息都展示出来当做传参,虽不影响使用,但容易混淆
这个时候可以在具体的实体类上追加一段注解,将对象所包含的属性默认隐藏
@ApiParam(hidden = true)
添加完成后当你不在controller配置的话,这些属性不会展示到swagger中
2.swagger在开发过程中好用,但是生产环境下必须屏蔽swagger,不然很容易让人利用swagger执行对库操作,安全隐患非常大,在springboot下可以通过多环境的yml配置文件来屏蔽生产环境下swagger的使用,具体配置如下:
在swagger的配置文件上加一行注解
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
然后再yml文件中配置:
swagger:
enable: true
生产环境下将true改为false这样swagger就不再展示