Swagger的使用

SpringBoot整合Swagger2

今天做一个小项目时用到了Swagger2，所以写篇随笔来记录一下.Swagger2的优点我就不多说了。

1. 导入依赖

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

2. 在主启动类的同级目录下创建Swagger2的配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * @Description:swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     */
    @Bean
    public Docket createRestApi() {

        // 为swagger添加header参数可供输入
        ParameterBuilder userTokenHeader = new ParameterBuilder();
        ParameterBuilder userIdHeader = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        userTokenHeader.name("headerUserToken").description("userToken")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        userIdHeader.name("headerUserId").description("userId")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        pars.add(userTokenHeader.build());
        pars.add(userIdHeader.build());

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.gt.video.controller"))  //要扫描的包
                .paths(PathSelectors.any()).build()
                .globalOperationParameters(pars);
    }

    /**
     * @Description: 构建 api文档的信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置页面标题
                .title("使用swagger2构建短视频后端api接口文档")
                // 设置联系人
                .contact(new Contact("gttttttt", "https://www.cnblogs.com/gttttttt", "2933253458@qq.com"))
                // 描述
                .description("欢迎访问短视频接口文档，这里是描述信息")
                // 定义版本号
                .version("1.0").build();
    }
}

3. 在Controller和pojo类上编写注解，为了方便演示，我们这里编写用户注册的Contrller

   
   @RestController
   @Api(value = "用户注册和登陆的接口",tags = {"用户注册和登陆的Controller"})
   public class RegistLoginController {
       @Autowired
       UsersService usersService;
      @PostMapping("/regist")
      @ApiOperation(value = "用户注册",notes = "用户注册的接口")
       public R regist(@RequestBody UsersEntity users) throws Exception {
           //1.判断用户名或密码是否为空
          if(StringUtils.isBlank(users.getUsername()) || StringUtils.isBlank(users.getPassword())){
              return R.error("用户名或密码不能为空");
          }
          //2.查询用户名是否存在
          QueryWrapper<UsersEntity> wrapper = new QueryWrapper<UsersEntity>();
          wrapper.eq("username",users.getUsername());
          UsersEntity usersEntity = usersService.getOne(wrapper);
          if(usersEntity!=null){
              return R.error("用户名已经存在了,请换一个吧");
          }
          //3.将用户信息保存在数据库
          users.setId(UUID.randomUUID().toString().replaceAll("-",""));
          users.setPassword(MD5Utils.getMD5Str(users.getPassword()));
          users.setFollowCounts(0);
          users.setReceiveLikeCounts(0);
          users.setFansCounts(0);
          users.setNickname(users.getUsername());
          usersService.save(users);
   
          users.setPassword("");
          return R.ok("注册成功").put("code",200).put("data",users);
      }
   }
   
   
   
   

   //这里使用了Lombok和Mybatisplus
   @Data
   @TableName("users")
   @ApiModel(value = "用户对象",description = "这是用户对象")
   public class UsersEntity implements Serializable {
   	private static final long serialVersionUID = 1L;
   
   	/**
   	 * 主键ID
   	 */
   	@TableId
   	private String id;
   	/**
   	 * 用户名
   	 */
       					//name对应字段名，example为示例，required表示必填
   	@ApiModelProperty(value = "用户名",name ="username",example = "gttttttt",required = true)
   	private String username;
   	/**
   	 * 密码
   	 */
   	@ApiModelProperty(value = "密码",name ="password",example = "1234567",required = true)
   	private String password;
   	/**
   	 * 用户照片
   	 */
   	@ApiModelProperty(hidden = true)	//表示提交请求时，该字段可以忽略不写
   	private String faceImage;
   	/**
   	 * 用户名
   	 */
   	@ApiModelProperty(hidden = true)
   	private String nickname;
   	/**
   	 * 
   	 */
   	@ApiModelProperty(hidden = true)
   	private Integer fansCounts;
   	/**
   	 * 
   	 */
   	@ApiModelProperty(hidden = true)
   	private Integer followCounts;
   	/**
   	 * $column.comments
   	 */
   	@ApiModelProperty(hidden = true)
   	private Integer receiveLikeCounts;
   
   }
   
   

   4. 在浏览器中输入http://localhost:8080:/swagger-ui.html
      

响应结果:

因为篇幅有限，所以截的图片不是很好。

5. 注解

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用" 
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        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：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

本篇随笔参考以下博客:

swagger2注解使用教程

Swagger2--Springboot使用

万分感谢!!!