[转]swagger2 入门教程
swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它
作用：
1、接口的文档在线自动生成
2、功能测试
先介绍它的常用注解
@Api 注解可以用来标记 Controller 的功能
@ApiOperation 注解用来标记一个方法的作用
@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入
@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中
@ApiModel 如果参数是一个对象，则需要在对象所在的类上加上此注解
@ApiModelProperty 如果参数是一个对象，则需要在对应的属性上加上此注解，还需要在对象所在的类上加上 @ApiModel
@ApiIgnore 注解标识此参数可以忽略
下面介绍它的使用
1、引入它的依赖
<!--写接口文档的api-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<artifactId>guava</artifactId>
<groupId>com.google.guava</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>${guava.version}</version>
</dependency>
<!--界面支持-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
2、使用开启注解 @EnableSwagger2 和 配置映射路径、要扫描的接口的未知、文档网站信息
package io.xiongdi.config; import io.swagger.annotations.ApiOperation; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.ApiKey; 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; /** * @author wujiaxing * <p> * 使用Swagger2只需三步 * 1、导入Swaggerr依赖 * 2、配置Docket的bean * 3、使用@Api等注解修饰 * </p> */ @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .select() // 方法需要有ApiOperation注解才能生存接口文档 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 路径使用any风格 .paths(PathSelectors.any()) .build() // 如何保护我们的Api，有三种验证（ApiKey, BasicAuth, OAuth） .securitySchemes(security()) // 接口文档的基本信息 .apiInfo(apiInfo()); } /** * 接口文档详细信息 * * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder().title("兄弟足浴").description("xd-api文档").termsOfServiceUrl("http://www.localhost:8002").version("1.0.0").build(); } private List<ApiKey> security() { ArrayList<ApiKey> apiKeys = new ArrayList<>(); apiKeys.add(new ApiKey("token", "token", "header")); return apiKeys; } }
3、使用它的注解标识要创建的接口文档
package io.xiongdi.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.xiongdi.annotation.Login; import io.xiongdi.common.utils.R; import io.xiongdi.common.validator.ValidatorUtils; import io.xiongdi.form.LoginForm; import io.xiongdi.service.TokenService; import io.xiongdi.service.UserService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import springfox.documentation.annotations.ApiIgnore; import java.util.Map; /** * @author wujiaxing * @date 2019-07-07 */ @Api(tags = "登录接口") @RequestMapping("/api") @RestController public class ApiLoginController { @Autowired private TokenService tokenService; @Autowired private UserService userService; @RequestMapping("login") @ApiOperation("登录") public R login(@RequestBody LoginForm loginForm) { // 服务端表单校验 System.out.println("已进入login"+loginForm); ValidatorUtils.validateEntity(loginForm); // 执行登录 Map<String, Object> map = userService.login(loginForm); return R.ok(map); } /** * <p> * 登出需要请求中带token * @RequestAttribute 这个注解表示访问有过滤器或拦截器创建的、预先存在的属性 * </p> * @param userId * @return */ @Login @ApiOperation("登出") @RequestMapping("logout") public R logout(@RequestAttribute("userId") @ApiIgnore long userId) { tokenService.expireToken(userId); return R.ok(); } }
package io.xiongdi.form; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; /** * 登录表单 * @author wujiaxing * @date 2019-06-30 */ @Data @ApiModel(value = "登录表单") public class LoginForm { @ApiModelProperty(value = "手机号") @NotBlank(message = "手机号不能为空") private String mobile; @ApiModelProperty(value = "密码") @NotBlank(message = "密码不能为空") private String password; }
4、正常来说，配置以上三步就可以了，但如果配置了跨域，则需要配置静态资源放过
package io.xiongdi.config; import io.xiongdi.interceptor.AuthorizationInterceptor; import io.xiongdi.resolver.LoginUserHandlerMethodArgumentResolver; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Configuration; import org.springframework.web.method.support.HandlerMethodArgumentResolver; import org.springframework.web.servlet.config.annotation.CorsRegistry; import org.springframework.web.servlet.config.annotation.InterceptorRegistry; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import java.util.List; /** * @author wujiaxing * <p> * 此配置类可配置拦截器、参数解析器、返回值解析器、跨域支持等等 * </p> */ @Configuration public class WebMvcConfig implements WebMvcConfigurer { @Autowired private AuthorizationInterceptor authorizationInterceptor; @Autowired private LoginUserHandlerMethodArgumentResolver loginUserHandlerMethodArgumentResolver; /** * 如果配置跨域，就增加这个配置 * @param registry */ @Override public void addResourceHandlers(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"); } /** * 拦截器配置 * @param registry */ @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(authorizationInterceptor).addPathPatterns("/api/**"); } /** * 跨域支持配置 * @param registry */ @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**").allowCredentials(true).allowedOrigins("*").allowedMethods("GET", "PUT", "DELETE", "POST", "OPTIONS").maxAge(3600); } /** * 参数解析配置 * @param resolvers */ @Override public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) { resolvers.add(loginUserHandlerMethodArgumentResolver); } }
至此基本配置已完成，访问 localhost:8080/swagger-ui.html
---------------------
作者：过儿写代码也在想姑姑
来源：CNBLOGS
原文：https://www.cnblogs.com/wujiaxing/p/11180361.html
版权声明：本文为作者原创文章，转载请附上博文链接！
内容解析By：CSDN,CNBLOG博客文章一键转载插件
