SpringBoot-Swagger整合

概述

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

引入依赖

<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>

常用swagger-ui注解

@Api() 用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代

@ApiOperation() 用于方法；表示一个http请求的操作
Value - 用于方法描述
Notes - 用于提示内容

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@ApiImplicitParam() 用于方法,表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

@ApiIgnore 作用于方法上，使用这个注解swagger将忽略这个接口

@ModelAttribute用于将请求参数绑定到Model对象

小案例

实体类中

@ApiModel(value = "TbSeller",description="商家对象模型")
@Table(name = "tb_seller")
public class TbSeller implements Serializable {
    /**
     * 商家id
     */
    @ApiModelProperty(value="id" ,required=false)
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private String id;
    ...
    ...
}

Controller中

@ApiOperation(value="检查验证码是否匹配")
@GetMapping("/checkAuthCode")
public String checkAuthCode(@ApiParam(name = "phoneOrEmail", value = "手机号或邮箱", required = true) @RequestParam("phoneOrEmail") String phoneOrEmail,
                            @ApiParam(name = "authCode", value = "验证码", required = true) @RequestParam("authCode") String authCode){
    String cacheCode = (String) redisTemplate.opsForValue().get(phoneOrEmail);
    if("".equals(cacheCode) || cacheCode == null){
        return "验证码已失效!";
    }
    if(cacheCode.equals(authCode)){
        return "Success";
    }
    return "Fail";
}
@ApiOperation(value="添加商家信息")
@PostMapping
public Result insert(@ModelAttribute TbSeller seller){
    seller.setId(new SnowFlake().nextId());
    seller.setRegisterDate(new Date());
    int insertNums = sellerService.insert(seller);
    if(insertNums > 0){
        return new Result(true,StatusCode.OK,"添加成功！");
    }
    return new Result(false,StatusCode.ERROR,"添加失败！");
}

若项目中添加了拦截器需对swagger放行

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import xyz.hclz.mobileshop.service.seller.interceptor.JwtInterceptor;

@Configuration
public class InterceptorConfig  extends WebMvcConfigurationSupport {
    @Autowired
    private JwtInterceptor jwtInterceptor;

    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        //注册拦截器声明拦截器对象和要拦截的请求
        registry.addInterceptor(jwtInterceptor)
                .addPathPatterns("/**/v/**");
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 放行swagger
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}