swagger注释API详细说明

转载:https://blog.csdn.net/xupeng874395012/article/details/68946676

链接:https://www.jianshu.com/p/12f4394462d5

API详细说明

注释汇总

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

 

作用在 controller 层:

 /**  Controller 层
     * 取消发布
     */
    @PostMapping("/exitpub")
    @ApiOperation(value = "图书取消发布",produces = "application/json", consumes="application/json")
    @RequiresPermissions("cms:bookresource:publish")
    @ApiImplicitParam(name="ids",allowMultiple = true,value = "id数组",required=true,paramType = "body",dataType="Long")
    public R unpublish(@PathVariable("ids") String[] ids){

 作用在实体层 entity

 @ApiModelProperty("编辑")
    @TableField(exist = false)
    private List<EditorEntity> editorList = new ArrayList<>();

 

@ApiImplicitParam

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

 

  @ApiImplicitParam(name = "id",value = "资源id",required=false,paramType = "path",dataType="Long")

 

 paramType 示例详解

path

@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

 @PathVariable(name = "id") Long id

 

body

 @ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
  @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)

  @RequestBody MessageParam param

  提交的参数是这个对象的一个json,然后会自动解析到对应的字段上去,也可以通过流的形式接收当前的请求数据,但是这个和上面的接收方式仅能使用一个(用@RequestBody之后流就会关闭了)

 

 

header

 @ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) 

   String idstr = request.getHeader("id");
        if (StringUtils.isNumeric(idstr)) {
            id = Long.parseLong(idstr);
        }

 

Form

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
 @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATIO

 

 常用 swagger 注解
常用到的注解有:
  • Api
  • ApiModel
  • ApiModelProperty
  • ApiOperation
  • ApiParam
  • ApiResponse
  • ApiResponses
  • ResponseHeader
1. api标记

Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。 属性配置:

属性名称备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏

在SpringMvc中的配置如下:

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {

}
2. ApiOperation标记

ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

与Controller中的方法并列使用。
属性配置:

属性名称备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map".,其他无效
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http的状态码 默认 200
extensions 扩展属性

在SpringMvc中的配置如下:

@RequestMapping(value = "/order/{orderId}", method = GET)
  @ApiOperation(
      value = "Find purchase order by ID",
      notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
      response = Order.class,
      tags = { "Pet Store" })
   public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
      throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
      return ok(order);
    } else {
      throw new NotFoundException(404, "Order not found");
    }
  }
3. ApiParam标记

ApiParam请求属性,使用方式:

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置:

属性名称备注
name 属性名称
value 属性值
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为false
hidden 隐藏该属性
example 举例子

在SpringMvc中的配置如下:

 public ResponseEntity<Order> getOrderById(
      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
      @PathVariable("orderId") String orderId)
4. ApiResponse

ApiResponse:响应配置,使用方式:

@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。 属性配置:

属性名称备注
code http的状态码
message 描述
response 默认响应类 Void
reference 参考ApiOperation中配置
responseHeaders 参考 ResponseHeader 属性配置说明
responseContainer 参考ApiOperation中配置

在SpringMvc中的配置如下:

 @RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity<String> placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }
5. ApiResponses

ApiResponses:响应集配置,使用方式:

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置:

属性名称备注
value 多个ApiResponse配置

在SpringMvc中的配置如下:

 @RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity<String> placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }
6. ResponseHeader

响应头设置,使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置:

属性名称备注
name 响应头名称
description 头描述
response 默认响应类 Void
responseContainer 参考ApiOperation中配置

在SpringMvc中的配置如下:

@ApiModel(description = "群组")
7. 其他
  • @ApiImplicitParams:用在方法上包含一组参数说明;
  • @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面@ApiResponses:用于表示一组响应;
    • paramType:参数放在哪个地方
    • name:参数代表的含义
    • value:参数名称
    • dataType: 参数类型,有String/int,无用
    • required : 是否必要
    • defaultValue:参数的默认值
  • @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息;@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候;
    • code: 响应码(int型),可自定义
    • message:状态码对应的响应信息
  • @ApiModelProperty:描述一个model的属性。

 


 




 

 

致敬:2020年的自己
--------------------------------------------
即使不为了什么远大理想,为了好好生活,你也得努力奋斗啊,不然别说什么风花雪月了,柴米油盐也能让你一筹莫展。
posted @ 2018-07-17 16:51  胖头陀春天  阅读(27893)  评论(4编辑  收藏  举报