Swagger UI — 介绍 与 使用

Swagger UI — 介绍 与 使用

一、Swagger 介绍

1. 概要

   Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2. 功能

   • 接口文档在线自动生成。
   • 功能测试。

二、Swagger 使用

1.引入依赖

通过 maven 导入Swagger：

    <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger2</artifactId>
          <version>2.6.1</version>
    </dependency>
    <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.6.1</version>
    </dependency>

2.注解说明

2.1 在实体类Eneity上

• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收。用在返回对象类上，描述一个Model的信息

• @ApiModelProperty()用于方法，字段

• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略

  @Data
  @ApiModel(value = "sys_data_source对象", description = "多数据源管理")
  public class SysDataSource {
  
      /**
       * id
       */
      @ApiModelProperty(value = "id")
      private java.lang.String id;
      /**
       * 数据源编码
       */
      @ApiModelProperty(value = "数据源编码")
      private java.lang.String code;
  
  }
  

2.2 在接口类上

• @Api()用于类；
  表示标识这个类是swagger的资源，说明该类的主要作用

  @Api(tags = "单表DEMO")
  @RestController
  @RequestMapping("/test/jeecgDemo")
  public class JeecgDemoController {
  
  }
  

• @ApiOperation()用于方法；
  表示一个http请求的操作，给API增加方法说明描述。

  @GetMapping(value = "/queryById")
  @ApiOperation(value = "通过ID查询DEMO", notes = "通过ID查询DEMO")
  public Result<?> queryById(@ApiParam(name = "id", value = "示例id", required = true) @RequestParam(name = "id", required = true) String id) {
      JeecgDemo jeecgDemo = jeecgDemoService.getById(id);
      return Result.OK(jeecgDemo);
  }
  

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

  @ApiParam(name = "id", value = "示例id", required = true)
  

• @ApiImplicitParam() 用于方法
  表示单独的请求参数，用来注解来给方法入参增加说明。

  @ApiImplicitParams() 用于方法，

  包含多个 @ApiImplicitParam，包含一组参数说明。

• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类

  @ApiResponses：用于表示一组响应。

2.3 完整案例

在开发中一般很少使用@ApiImplicitParam 作为参数的描述，这样描述在参数过多的条件下会有点麻烦。个人一般是将参数封装为一个完整对象（特别是GET方法），并利用@ApiModel注解去定义参数，如果不需要作为查询条件的，则加一个hidden = true，如果是必填属性，则增加一个required = true即可。

1. API接口：

   @Api(tags = "单表DEMO")
   @RestController
   @RequestMapping("/test/jeecgDemo")
   public class JeecgDemoController {
   @Autowired
   private IJeecgDemoService jeecgDemoService;
   
   
       /**
       * 批量删除
       *
       * @param ids
       * @return
       */
       @DeleteMapping(value = "/deleteBatch")
       @ApiOperation(value = "批量删除DEMO", notes = "批量删除DEMO")
       public Result<?> deleteBatch(@RequestParam(name = "ids", required = true) String ids) {
           this.jeecgDemoService.removeByIds(Arrays.asList(ids.split(",")));
           return Result.OK("批量删除成功！");
       }
   
       /**
       * 通过id查询
       *
       * @param id
       * @return
       */
       @GetMapping(value = "/queryById")
       @ApiOperation(value = "通过ID查询DEMO", notes = "通过ID查询DEMO")
       public Result<?> queryById(@ApiParam(name = "id", value = "示例id", required = true) @RequestParam(name = "id", required = true) String id) {
           JeecgDemo jeecgDemo = jeecgDemoService.getById(id);
           return Result.OK(jeecgDemo);
       }
   }
   

2. entity：

       @Data
       @ApiModel(value="测试DEMO对象", description="测试DEMO")
       public class JeecgDemo extends JeecgEntity implements Serializable {
   
           private static final long serialVersionUID = 1L;
   
           /** 部门编码 */
           @ApiModelProperty(value = "部门编码")
           private java.lang.String sysOrgCode;
   
           /** 姓名 */
           @ApiModelProperty(value = "姓名")
           private java.lang.String name;
   
           /** 关键词 */
           @ApiModelProperty(value = "关键词")
           private java.lang.String keyWord;
   
       }
   
   

3. API数据返回

   	@Data
       @ApiModel(value="接口返回对象", description="接口返回对象")
       public class Result<T> implements Serializable {
   
           private static final long serialVersionUID = 1L;
   
           /**
            * 成功标志
            */
           @ApiModelProperty(value = "成功标志")
           private boolean success = true;
   
           /**
            * 返回处理消息
            */
           @ApiModelProperty(value = "返回处理消息")
           private String message = "操作成功！";
   
           /**
            * 返回代码
            */
           @ApiModelProperty(value = "返回代码")
           private Integer code = 0;
   
           /**
            * 返回数据对象 data
            */
           @ApiModelProperty(value = "返回数据对象")
           private T result;
   
           /**
            * 时间戳
            */
           @ApiModelProperty(value = "时间戳")
           private long timestamp = System.currentTimeMillis();
   
       }
   

参考资料

https://www.jianshu.com/p/a0caf58b3653

https://www.jianshu.com/p/a0caf58b3653