使用流程如下:
1)引入相应的 maven 包:
<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的 配置 类:
@EnableSwagger2
public class Swagger2Config {
@Value("${swagger2.enable}")
private boolean enable;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("api1") //分组
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.ours.controller"))
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.enable(enable); //是否关闭文档
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2构建RESTful APIs")
.description("ours_admin")
.version("1.0.0")
.build();
}
@Bean
public Docket createRestApi1() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("api2") //分组
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.ant("/api/sys/**"))
.build();
}
/**
* 增加auth验证
*/
private List<ApiKey> securitySchemes() {
return Lists.newArrayList(
new ApiKey("Authorization", "Authorization", "header"));
}
private List<SecurityContext> securityContexts() {
return Lists.newArrayList(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.any())
.build()
);
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Lists.newArrayList(
new SecurityReference("Authorization", authorizationScopes));
}
}
- 通过注解@EnableSwagger2开启swagger2,apiInfo是接口文档的基本说明信息,包括 标题 、描述、服务网址、联系人、版本等信息;
- 在Docket创建中,通过groupName进行分组,paths属性进行过滤,apis属性可以设置扫描包,或者通过注解的方式标识;通过enable属性,可以在properties文件中设置相应值,主要用于控制生产环境不生成接口文档。
- 在spring配置文件中声明 <bean id="swagger2Config" class="com.ours.config.Swagger2Config"/>
3)在controller层类和方法添加注解
@Api(description = "系统", tags = "/api/sys")
@RestController
@RequestMapping(value = "/api/sys/")
public class SystController {
@ApiOperation(value = "获取配置信息", notes = "根据id获取")
@RequestMapping(value = "get/{id}", method = {RequestMethod.POST})
public HttpResponseResult test(@PathVariable Integer id) {
return new HttpResponseResult().success(true);
}
}
4)返回对象HttpResponseResult
@Data
@ApiModel("返回信息")
public class HttpResponseResult<T> implements Serializable {
private static final long serialVersionUID = 2525646670546276251L;
@ApiModelProperty("返回code")
private String code;
@ApiModelProperty("返回消息内容")
private String message;
@ApiModelProperty("内容")
private T data;
public HttpResponseResult() {
}
public HttpResponseResult(String code, String message, T data) {
this.code = code;
this.message = message;
this.data = data;
}
public HttpResponseResult(String code, String message) {
this.code = code;
this.message = message;
}
public HttpResponseResult success(T data) {
this.data = data;
this.code = "success";
this.message = "请求成功";
return this;
}
public HttpResponseResult fail() {
this.code = "fail";
this.message = "请求失败";
return this;
}
}
5)常用注解
@Api:用在请求的类上,表示对类的说明
- tags "说明该类的作用,可以在UI界面上看到的注解"
- value "该 参数 没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
- value="说明方法的用途、作用"
- notes="方法的备注说明"
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- value:参数的汉字说明、解释
- required:参数是否必须传
- paramType:参数放在哪个地方
- header –> 请求参数的获取:@RequestHeader
- query –> 请求参数的获取:@RequestParam
- path(用于restful接口)–> 请求参数的获取:@PathVariable
- body(不常用)
- form(不常用)
- dataType:参数类型,默认String,其它值dataType="Integer"
- defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- code:数字,例如400
- message:信息,例如"请求参数没填好"
- response:抛出异常的类
@ApiModel:主要有两种用途:
- 用于响应类上,表示一个返回响应数据的信息
- 入参实体:使用@RequestBody这样的场景, 请求参数无法使用@ApiImplicitParam注解进行描述的时候
@ApiModelProperty:用在属性上,描述响应类的属性
最终生成文档