swagger2是一个在线生成文档和测试功能的软件,使用很简单,大概说一下步骤。
一、在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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public class Swagger2 {
@Bean
public Docket createRestApi() {
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("Authorization").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.zp")) //根据自己具体要扫描api的路径,就是接口路径。
.paths(PathSelectors.any()) // 对所有路径进行监控
.build()
.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("springboot项目接口文档")
.termsOfServiceUrl("")
.contact("iamapsycho")
.version("1.0")
.build();
}
}
}
三、启动工程,访问localhost//swagger-ui.html即可。
四、具体使用
配置swagger还可以很精细,可以根据自己需要进行配置,比如扫描的具体包等。在代码中使用swagger功能,即可生成文档,具体百度很多。
1、@Api:请求类的说明:
tags:"说明该类的作用" 。value="该参数没什么意义,跟tags一样,所以不配置。
例子:@Api(tags = "消费分析")
2、@ApiOperation
value:表示的是方法名称
notes:表示的是方法描述,如接口描述
例子:@ApiOperation(value="商户热力地图",notes="热力地图,展示消费区域情况。")
3、@ApiImplicitParams:请求参数说明:
name = 参数字符名称
required :参数是否必须
dataType:参数类型,默认String,其它值dataType="int"
value :参数中文备注说明
例子:@ApiImplicitParams({
@ApiImplicitParam(name = "unitCode", value = "99全部", required = false,
paramType = "query", dataType = "String")
4、返回参数实体类:
@ApiModel在实体类的方法上:
@ApiModelProperty:属性类的实体上面,
属性上面,说明属性的含义。
@ApiModel(description= "返回响应数据")
@ApiModelProperty(value = "是否成功")
5、返回约定(可以不写,约定写在公共文件头就行):
@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
例子:
@ApiResponses({
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})