swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它
作用:
1、接口的文档在线自动生成
2、功能测试
先介绍它的常用注解
@Api 注解可以用来标记 Controller 的功能
@ApiOperation 注解用来标记一个方法的作用
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中
@ApiModel 如果参数是一个对象,则需要在对象所在的类上加上此注解
@ApiModelProperty 如果参数是一个对象,则需要在对应的属性上加上此注解,还需要在对象所在的类上加上 @ApiModel
@ApiIgnore 注解标识此参数可以忽略
下面介绍它的使用
1、引入它的依赖
io.springfox
springfox-swagger2
${swagger.version}
guava
com.google.guava
com.google.guava
guava
${guava.version}
io.springfox
springfox-swagger-ui
${swagger.version}
2、使用开启注解 @EnableSwagger2 和 配置映射路径、要扫描的接口的未知、文档网站信息
packageio.xiongdi.config;importio.swagger.annotations.ApiOperation;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importspringfox.documentation.builders.ApiInfoBuilder;importspringfox.documentation.builders.PathSelectors;importspringfox.documentation.builders.RequestHandlerSelectors;importspringfox.documentation.service.ApiInfo;importspringfox.documentation.service.ApiKey;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;importspringfox.documentation.swagger2.annotations.EnableSwagger2;importjava.util.ArrayList;importjava.util.List;/***@authorwujiaxing
*
* 使用Swagger2只需三步
* 1、导入Swaggerr依赖
* 2、配置Docket的bean
* 3、使用@Api等注解修饰
*
*/@Configuration@EnableSwagger2public classSwaggerConfig {
@BeanpublicDocket createRestApi() {return newDocket(DocumentationType.SWAGGER_2)
.select()//方法需要有ApiOperation注解才能生存接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//路径使用any风格
.paths(PathSelectors.any())
.build()//如何保护我们的Api,有三种验证(ApiKey, BasicAuth, OAuth)
.securitySchemes(security())//接口文档的基本信息
.apiInfo(apiInfo());
}/*** 接口文档详细信息
*
*@return
*/
privateApiInfo apiInfo() {return new ApiInfoBuilder().title("兄弟足浴").description("xd-api文档").termsOfServiceUrl("http://www.localhost:8002").version("1.0.0").build();
}private Listsecurity() {
ArrayList apiKeys = new ArrayList<>();
apiKeys.add(new ApiKey("token", "token", "header"));returnapiKeys;
}
}
3、使用它的注解标识要创建的接口文档
packageio.xiongdi.controller;importio.swagger.annotations.Api;importio.swagger.annotations.ApiOperation;importio.xiongdi.annotation.Login;importio.xiongdi.common.utils.R;importio.xiongdi.common.validator.ValidatorUtils;importio.xiongdi.form.LoginForm;importio.xiongdi.service.TokenService;importio.xiongdi.service.UserService;importorg.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.*;importspringfox.documentation.annotations.ApiIgnore;importjava.util.Map;/***@authorwujiaxing
* @date 2019-07-07*/@Api(tags= "登录接口")
@RequestMapping("/api")
@RestControllerpublic classApiLoginController {
@AutowiredprivateTokenService tokenService;
@AutowiredprivateUserService userService;
@RequestMapping("login")
@ApiOperation("登录")publicR login(@RequestBody LoginForm loginForm) {//服务端表单校验
System.out.println("已进入login"+loginForm);
ValidatorUtils.validateEntity(loginForm);//执行登录
Map map =userService.login(loginForm);returnR.ok(map);
}/***
* 登出需要请求中带token
* @RequestAttribute 这个注解表示访问有过滤器或拦截器创建的、预先存在的属性
*
*@paramuserId
*@return
*/@Login
@ApiOperation("登出")
@RequestMapping("logout")public R logout(@RequestAttribute("userId") @ApiIgnore longuserId) {
tokenService.expireToken(userId);returnR.ok();
}
}
packageio.xiongdi.form;importio.swagger.annotations.ApiModel;importio.swagger.annotations.ApiModelProperty;importlombok.Data;importjavax.validation.constraints.NotBlank;/*** 登录表单
*@authorwujiaxing
* @date 2019-06-30*/@Data
@ApiModel(value= "登录表单")public classLoginForm {
@ApiModelProperty(value= "手机号")
@NotBlank(message= "手机号不能为空")privateString mobile;
@ApiModelProperty(value= "密码")
@NotBlank(message= "密码不能为空")privateString password;
}
4、正常来说,配置以上三步就可以了,但如果配置了跨域,则需要配置静态资源放过
packageio.xiongdi.config;importio.xiongdi.interceptor.AuthorizationInterceptor;importio.xiongdi.resolver.LoginUserHandlerMethodArgumentResolver;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.context.annotation.Configuration;importorg.springframework.web.method.support.HandlerMethodArgumentResolver;importorg.springframework.web.servlet.config.annotation.CorsRegistry;importorg.springframework.web.servlet.config.annotation.InterceptorRegistry;importorg.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;importorg.springframework.web.servlet.config.annotation.WebMvcConfigurer;importjava.util.List;/***@authorwujiaxing
*
* 此配置类可配置拦截器、参数解析器、返回值解析器、跨域支持等等
*
*/@Configurationpublic class WebMvcConfig implementsWebMvcConfigurer {@AutowiredprivateAuthorizationInterceptor authorizationInterceptor;
@AutowiredprivateLoginUserHandlerMethodArgumentResolver loginUserHandlerMethodArgumentResolver;/*** 如果配置跨域,就增加这个配置
*@paramregistry*/@Overridepublic voidaddResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**").addResourceLocations("/static/");
registry.addResourceHandler("/js/**").addResourceLocations("/js/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");
}/*** 拦截器配置
*@paramregistry*/@Overridepublic voidaddInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(authorizationInterceptor).addPathPatterns("/api/**");
}/*** 跨域支持配置
*@paramregistry*/@Overridepublic voidaddCorsMappings(CorsRegistry registry) {
registry.addMapping("/**").allowCredentials(true).allowedOrigins("*").allowedMethods("GET", "PUT", "DELETE", "POST", "OPTIONS").maxAge(3600);
}/*** 参数解析配置
*@paramresolvers*/@Overridepublic void addArgumentResolvers(Listresolvers) {
resolvers.add(loginUserHandlerMethodArgumentResolver);
}
}
至此基本配置已完成,访问 localhost:8080/swagger-ui.html