[Swagger2]分组和接口注释及小结

Posted 2022-03-07 唐火

分组和接口注释及小结

配置API分组

1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) 
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....

2、重启项目查看分组

3、如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1()
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");

@Bean
public Docket docket2()
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");

@Bean
public Docket docket3()
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");

4、重启项目查看即可

实体配置

package com.xxxx.swagger2.pojo;


import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

// 等价于@Api()
@ApiModel("用户实体类")
public class User 

    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String passwrod;

package com.xxxx.swagger2.controller;

import com.xxxx.swagger2.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;



@Api(tags = "Hello控制类")
@RestController
public class HelloController 

    @GetMapping(value = "/hello")
    public String hello()
    
        return "hello";
    


    // 只要我们的接口中,返回值中存在实体类,它就会被扫描到Swagger中
    @PostMapping(value = "/user")
    public User user()
    
        return new User();
    



    // Operation 接口 不是放在类上的,是方法
    @ApiOperation("HelloController中的hello2方法")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username)
    
        return "hello"+username;
    

    @ApiOperation("Post测试类")
    @GetMapping(value = "/postt")
    public User postt(@ApiParam("用户名") User user)
    
        return user;
    

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

我们也可以给请求的接口配置一些注释

@ApiOperation("接口")
@PostMapping("/kuang")
@ResponseBody
public String kuang(@ApiParam("这个名字会被返回")String username)
   return username;

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。