Swagger 常用註解使用講解

講解內容

1. swagger常用到的註解的解釋
2. SpringMVC中控制層類中使用這些註解

swagger常用到的註解的解釋

在pom.xml文件中添加包依賴：swagger-annotations-1.5.10.jar

所有註解：

常用到的註解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

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

定義後swagger效果圖： 

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的值會被覆蓋
notes	對api資源的描述
response	返回的對象
responseContainer	這些對象是有效的 "List", "Set" or "Map".，其他無效
responseReference	可以不配置
httpMethod	可以接受 "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position	如果配置多個Api 想改變顯示的順序位置
produces	同 Api中的定義
consumes	同 Api中的定義
protocols	同 Api中的定義
authorizations	同 Api中的定義
hidden	同 Api中的定義
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");
    }
  }

swagger效果圖： 

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	舉例子
examples

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

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("");
  }

效果圖展示： 

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("");
  }

ResponseHeader相應配置

使用方式：

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

與Controller中的方法並列使用。 屬性配置：

屬性名稱	備註	默認值
name	響應頭名稱
description	頭描述
response	默認響應類 Void
responseContainer	參考ApiOperation中配置

在SpringMvc中的配置如下：

@ApiModel(description = "羣組")

ApiModel相應配置

使用方式：

description="描述實體的作用"  

屬性配置：

屬性名稱	備註	默認值
value	默認爲類的名稱
description	對該類的描述
parent	可以不配置
discriminator	可以不配置
subTypes	可以不配置
reference	引用配置可以不考慮

在SpringMvc中的配置如下：

@ApiModel(description = "羣組")
public class UamGroup {}

ApiModelProperty相應配置

使用方式：

@ApiModelProperty(required = true, value = "羣組的Id")

屬性配置：

屬性名稱	備註	默認值
value	屬性描述
name	如果配置覆蓋屬性名稱
allowableValues	參考ApiParam配置項項
access	可以不配置
notes	沒有使用
dataType	數據類型
required	參考ApiParam配置項項
position	參考ApiOperation配置項
hidden	參考ApiOperation配置項
example	參考ApiParam配置項項
readOnly
reference	參考ApiParam配置項項

在SpringMvc中的配置如下：

@ApiModelProperty(required = true, value = "羣組的Id")
    private String groupId;