- 接口文档访问接口:http://localhost:8080/swagger-ui.html
分析和效果演示
- 分析
- 效果
配置
pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
配置类
- 实现WebMvcConfigurer 接口
- 要填自己的控制器位置路径
- 若打算关闭显示则在以下
return new Docket(DocumentationType.SWAGGER_2)
最后面加.enable(false);
(一般用于环境区分,线上环境就不显示)
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket productApi() {
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2).select()
.apis(RequestHandlerSelectors.basePackage("com.edt.trip.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars)
.apiInfo(metaData());
}
private ApiInfo metaData() {
return new ApiInfoBuilder()
.title("SpringBoot集成Swagger2")
.description("豪行天下项目接口文档")
.version("1.0.0")
.license("Apache License Version 2.0")
.licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
.build();
}
@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/");
}
}
使用
控制器
- 贴
@Api(value = "用户资源", description = "用户资源控制器")
说明控制器
控制器方法
- 贴
@ApiOperation(value = "注册功能", notes = "其实就是新增用户")
说明方法 - 贴
@ApiImplicitParams({ @ApiImplicitParam(value = "手机号", name = "phone", dataType = "String", required = true) })
说明参数
@ApiResponses({ @ApiResponse(code = 200, message = "用户注册成功") })
- 用在@ApiResponses中,一般用于表达一个错误的响应信息(200相应不写在这里面)
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出的异常类
- 贴
@ApiIgnore
在接口方法上,表示不显示此接口在文档上
实体类
- 贴
@Api(value = "用户",description = "平台注册用户模型")
说明对象 - 贴
@ApiModelProperty(value="昵称",name="nickName",dataType = "String",required = true)
说明属性
拦截处理
- 一些项目会有拦截器类拦截路径,所以要配置开放该swagger接口文档url
- 拦截器的类 重写以下
addInterceptors
方法即可
@Configuration
public class WebConfigurer extends WebMvcConfigurationSupport {
@Resource
private DateConverterConfig dateConverterConfig;
@Resource
private SecurityControlInterceptor securityControlInterceptor;
@Override
protected void addInterceptors(InterceptorRegistry registry) {
String[] swaggerExcludes=new String[]{"/swagger-ui.html","/swagger-resources/**","/webjars/**"};
securityControlInterceptor.init();
registry.addInterceptor(securityControlInterceptor).addPathPatterns("/**").excludePathPatterns(swaggerExcludes);
super.addInterceptors(registry);
}
@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/");
}
@Override
protected void addFormatters(FormatterRegistry registry) {
registry.addConverter(dateConverterConfig);
}
}