swagger 深度使用

以你之姓@ 2022-05-26 03:35 105阅读 0赞

业务需求  因为是前后端分离项目，存在前后端都深刻理解业务的逻辑，及其字段含义，为了减少前后端交互成本，所以利用swagger 来进行下列工作

## API详细说明 ##

注释汇总

<table> 
 <thead> 
  <tr> 
   <th>作用范围</th> 
   <th>API</th> 
   <th>使用位置</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>对象属性</td> 
   <td>@ApiModelProperty</td> 
   <td>用在出入参数对象的字段上</td> 
  </tr> 
  <tr> 
   <td>协议集描述</td> 
   <td>@Api</td> 
   <td>用于controller类上</td> 
  </tr> 
  <tr> 
   <td>协议描述</td> 
   <td>@ApiOperation</td> 
   <td>用在controller的方法上</td> 
  </tr> 
  <tr> 
   <td>Response集</td> 
   <td>@ApiResponses</td> 
   <td>用在controller的方法上</td> 
  </tr> 
  <tr> 
   <td>Response</td> 
   <td>@ApiResponse</td> 
   <td>用在 @ApiResponses里边</td> 
  </tr> 
  <tr> 
   <td>非对象参数集</td> 
   <td>@ApiImplicitParams</td> 
   <td>用在controller的方法上</td> 
  </tr> 
  <tr> 
   <td>非对象参数描述</td> 
   <td>@ApiImplicitParam</td> 
   <td>用在@ApiImplicitParams的方法里边</td> 
  </tr> 
  <tr> 
   <td>描述返回对象的意义</td> 
   <td>@ApiModel</td> 
   <td>用在返回对象类上</td> 
  </tr> 
 </tbody> 
</table>

1.样例数据

![70][]

# @ApiImplicitParam #

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>取值</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td>&nbsp;</td> 
   <td>查询参数类型</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>path</td> 
   <td>以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>query</td> 
   <td>直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>body</td> 
   <td>以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>header</td> 
   <td>参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>form</td> 
   <td>以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>&nbsp;</td> 
   <td>参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>Long</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>String</td> 
   <td>&nbsp;</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>&nbsp;</td> 
   <td>接收参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>&nbsp;</td> 
   <td>接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>&nbsp;</td> 
   <td>参数是否必填</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>true</td> 
   <td>必填</td> 
  </tr> 
  <tr> 
   <td>&nbsp;</td> 
   <td>false</td> 
   <td>非必填</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>&nbsp;</td> 
   <td>默认值</td> 
  </tr> 
 </tbody> 
</table>

代码

@CrossOrigin
         @GetMapping    
    
        @ApiOperation(value = "更新数据字典数据",notes = "码表主键:ID(必填项)<br/>")
        @ApiImplicitParams({
                @ApiImplicitParam(name="itemname",value = "名称",defaultValue = "T1-3",paramType = "query",required = false),
                @ApiImplicitParam(name="dictype",value = "字典类型",defaultValue = "MarketType",paramType = "query",required = false),
                @ApiImplicitParam(name="pagenum",value = "第几页",defaultValue = "1",paramType = "query",required = true),
                @ApiImplicitParam(name="pagesize",value = "每页几条",defaultValue = "5",paramType = "query",required = true),
        })
        public ResultVO getCommonDictionaryItemList(@RequestParam("itemname")String itemname,@RequestParam("dictype")String dictype,@RequestParam("pagenum")int pagenum, @RequestParam("pagesize")int pagesize){
    
            PageUtil<CommonDictionaryItem> pageUtil= commonDictionaryItemService.getCommonDictionaryItemList(itemname,dictype,pagenum,pagesize);
    
            return ResultVOUtil.success(pageUtil);
        }

2.属性对应

![70 1][]

代码

@ApiModel(value = "审批日志entity")
     public class xxx implements Serializable{ 
        @ApiModelProperty(name="id",value = "主键id",example = "1",readOnly = true) 
        private Integer id; 
    
        @ApiModelProperty(value = "用户编号") 
        private String usercode; 
        @ApiModelProperty(value = "用户名称")  
       private String username;
       @ApiModelProperty(value = "审批状态")  
       private String auditingstateid; 
        @ApiModelProperty(value = "审批状态名称") 
        private String auditingstatename;
     @ApiModelProperty(value = "审批时间")  
       private Date auditingtime;
    }

3.注意事项

![70 2][]

![70 3][]

4.标题的修改

![70 4][]

private ApiInfo apiInfo(){
    		return new ApiInfoBuilder()
    				.title("DLX-api文档")
    				.description("提供给外部系统的服务接口，进行管理业务。")
    				.termsOfServiceUrl("http://terms-of-services.url")
    				.version("1.0")
    				.build();
    	}

[70]: /images/20220526/f8a648a8f52a42208253949941b0b5bd.png
[70 1]: /images/20220526/7b669eb22e124285b5421cd82ac9b269.png
[70 2]: /images/20220526/df01d8f8a65046b2a7a99e30cc240f14.png
[70 3]: /images/20220526/760b450c1f3f4954b83f2b3a60a81fb8.png
[70 4]: /images/20220526/223a9d07cef3461bbf4bcc8ce29197cf.png