[@Api]

@ Api用於宣告Swagger資源API。 它有雙重用途 - 它會

影響資源列表_和_ API宣告。 只有使用@ Api註釋的類才會被Swagger掃描。

在資源清單中，註釋將轉換為[資源物件]

在API宣告中，它基本上將作為[API宣告]本身的基礎。

JAX-RS的用法是:

@Api(tags = "區域：/area", description = "地區的增刪查改")
@RestController
@RequestMapping(value = "area", produces = {"application/json;charset=UTF-8"})
@ApiResponses(value = {
        @ApiResponse(code = 400, message = "系統異常", response = RedisService.class),
        @ApiResponse(code = 401, message = "測試異常", response = AreaMapper.class)
})
public class AreaController {
    ...
}
 

顯示效果

[@ApiOperation]

@ ApiOperation用於在API資源中宣告單個操作。 操作被認為是路徑和HTTP方法的唯一組合。 只掃描使用@ ApiOperation註釋的方法並新增API宣告。

註釋將影響Swagger輸出的兩個部分，[API物件]，每個路徑將建立一個，以及[操作物件]，將根據@ApiOperation建立一個。 請記住，在使用Servlet時，@ Api會在設定路徑時影響API物件。

JAX-RS的用法是

    @ApiOperation(value = "根據areaId獲取地區", notes = "根據url的id來獲取地區")
    @RequestMapping(value = " {areaId}", method = RequestMethod.GET)
    public Map<String, Object> getArea(@PathVariable("areaId") Integer areaId) {
        ...
    }
 

使用效果

[@ApiResponses], [@ApiResponse]

使用HTTP狀態程式碼返回錯誤（或其他成功訊息）是一種常見做法。 雖然操作的常規返回型別在[@ApiOperation]中定義，但應使用這些註釋描述其餘的返回程式碼。

@ ApiResponse描述了具體的可能響應。 它不能直接在方法上使用，需要包含在@ ApiResponses的陣列值中（無論是否有一個響應或更多）。

如果響應伴隨身體，也可以描述身體模型（每個響應一個模型）。

用法（JAX-RS，Servlet或其他）之間的使用沒有區別：

    @RequestMapping(value = " {areaId}", method = RequestMethod.GET)
    @ApiResponses(value = {
            @ApiResponse(code = 400, message = "系統異常", response = RedisService.class),
            @ApiResponse(code = 401, message = "測試異常", response = AreaMapper.class)
    })
    public Map<String, Object> getArea(@PathVariable("areaId") Integer areaId) {
         ...
    }
 

有關此註釋，用法和邊緣情況的更多詳細資訊，請檢視javadoc ([@ApiResponses], [@ApiResponse]**.

[@ApiParam]

@ ApiParam僅用於JAX-RS引數註釋（@PathParam，@ QueryParam，@HeaderParam，@ FormParam和JAX-RS 2，@ BeanParam）。 雖然swagger-core預設掃描這些註釋，但@ ApiParam可用於新增有關引數的更多詳細資訊，或在從程式碼中讀取時更改值。

在Swagger規範中，這轉換為[引數物件]。

Swagger將獲取這些註釋的value（）並將它們用作引數名稱，並根據註釋設定引數型別。 對於body引數（JAX-RS方法的單個輸入引數），名稱將自動設定為body（根據Swagger規範的要求）。

如果存在，Swagger還將使用@ DefaultValue的值作為預設值屬性。

    @RequestMapping(method = RequestMethod.POST)
    public Map<String, Object> addArea(
           @ApiParam(value = "地區名稱",required = true) String areaName,
           @ApiParam(value = "地區domain",required = true) @RequestBody  Area area) {
           ...
    }

這裡我們有兩個引數。 第一個是areaName，它是路徑的一部分。 第二個是正文，在本例中是一個Area物件。 請注意，兩個引數都將required屬性設定為true。 對於@PathParam，這是多餘的，因為預設情況下它是強制性的，不能被覆蓋。

輸出將是:

有關此註釋，用法和邊緣情況的更多詳細資訊，請檢視 javadocs.

[@ApiImplicitParam], [@ApiImplicitParams]

您可能希望手動描述操作引數。 這可能有多種原因，例如：

• 使用不使用JAX-RS註釋的Servlet.
• 想要隱藏定義的引數，並使用完全不同的定義覆蓋它.
• 描述在到達JAX-RS實現之前過濾器或其他資源使用的引數.

由於可以包含幾個引數，@ ApiImplicitParams允許多個@ ApiImplicitParam定義。

在Swagger規範中，這些轉換為[Parameter Object]。

在隱式定義引數時，為Swagger的定義設定name，dataType和paramType是很重要的。

 @ApiImplicitParams({
            @ApiImplicitParam(name = "areaName", value = "地區名稱", required = true, dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "priority", value = "地區編號", required = false, dataType = "string", paramType = "query"),
            @ApiImplicitParam(name = "id", value = "地區id", required = true, dataType = "long", paramType = "query")
    })
    @RequestMapping(value = "editArea", method = RequestMethod.POST)
    public Map<String, Object> editArea(Area area) {
        ...
    }

在上面的示例中，我們可以看到具有多個引數的Servlet定義。 dataType可以是基元名稱或類名稱。 paramType可以是Swagger支援的任何引數型別（有關更多詳細資訊，請參閱javadoc或規範）.

[@ApiModel]

Swagger-core在整個API內省中基於對它們的引用構建模型定義。 @ ApiModel允許您操作模型的元資料，從簡單的描述或名稱更改到多型的定義。

這轉換為Swagger規範中的[Model Object]。

在其基本功能中，您可以使用@ ApiModel來更改模型的名稱併為其新增描述：

@ApiModel(value = "區域domain",description = "區域的資料庫模型")
public class Area {
     ...

}

我們將模型的名稱從Area更改為區域domain

為了支援多型和繼承，我們使用discriminator和subTypes欄位。 兩者都必須用於Swagger輸出才有效。

“discriminator”欄位必須是頂部模型中的欄位，該欄位將用於確定正在使用哪個子模型。 例如，如果您有一個Animal類，其中Cat，Dog和Chicken作為子類，則animalType欄位可以用作鑑別器來確定實際使用的是哪種動物。

subTypes必須列出繼承模型的類。 類本身不必從超型別繼承。 事實上，Swagger不會自動讀取擴充套件類，你必須在subTypes中手動描述這些類，以便對它們進行解析。

@ApiModel(value="SuperModel", discriminator = "foo", subTypes = {SubModel.class})
public class SuperModel {...}

@ApiModel(value="SubModel")
public class SubModel {...}

上面的程式碼片段是一個如何描述繼承的簡單示例。 注意SubModel不會擴充套件SuperModel。 以同樣的方式，您可以新增多個繼承類。 可以有任意數量的繼承級別

For further details about this annotation, usage and edge cases, check out the javadocs.

[@ApiModelProperty]

雖然swagger-core將內省欄位和setter / getter，但它也會讀取和處理JAXB註釋。 @ ApiModelProperty允許控制Swagger特定的定義，例如允許的值和附加註釋。 如果您想在某些情況下隱藏屬性，它還提供其他過濾屬性。

有關Swagger Spec中的相關資訊，請檢視Property Object.

public class Area {
    @ApiModelProperty(value = "區域id", required = true, position = 1, example = "1")
    private Integer areaId;

    @ApiModelProperty(value = "區域名稱", required = true, position = 2, example = "北京")
    private String areaName;

    @ApiModelProperty(value = "區域編號", required = true, position = 3, example = "10001")
    private Integer priority;

    @ApiModelProperty(value = "新增時間", required = false, position = 4, example = "2017-02-02")
    private Date createTime;

    @ApiModelProperty(value = "最後修改時間", required = false, position = 5, example = "2017-02-02")
    private Date lastEditTime;

}

這是向模型屬性新增簡短描述的簡單示例。 還可以觀察到，雖然status是一個String，但我們將其記錄為只有三個可能的值。

有關此註釋，用法和邊緣情況的更多詳細資訊，請檢視javadocs.