常用註解使用規範

寫這部分內容是因為Swagger註解有的屬性設定後無效，有的屬性設定後會使可讀性降低（頁面顯示效果不好），所以在這記錄一下個人認為比較簡潔的設定方式

@Api

設定 tag 屬性即可，value 會被 tags 替代沒卵用，tag 屬性的內容會被顯示到 Controller 類名前

@ApiOperation

只指定 value 屬性對介面進行簡單描述即可，該屬性會顯示到請求路徑之後，設定 tags 屬性會在頁面上單獨將該方法顯示出來，比較亂，不推薦設定

@ApiParam

不需要指定 name，指定 value 和 required 即可，name 的作用是更改引數的顯示名稱，這樣的話前端會將 name 的值而不是實際的引數名稱當作傳參時的引數名稱，容易產生混淆，自找麻煩，並且 name 屬性對於使用了 @RequestBody 註解的引數不起作用

@ApiModel

新增 description 屬性即可，該屬性會被新增到 models 列表中 model 的 description 欄位，value 作用和上述的 name 作用類似，會對 model 改名顯示，容易產生混淆

@ApiModelProperty

value 為屬性的簡單描述，example 指定該屬性的示例值，required指定是否為必須，三個屬性都可以指定

控制器註解的位置

Swagger是一個用來生成介面文件的工具，既然是生成介面文件，那麼就不必關心業務的具體實現，平時在開發過程中也都是先定義介面，需要的時候再去建立Controller實現對應業務的介面，所以Swagger關於控制器的註解如 @Api

這樣做的好處有：

• 介面實現類不用關心不屬於業務範疇的（介面文件生成）相關操作
• 介面實現類的內容更加簡潔
• 針對開放Api，Swagger的註解可以替代註釋的角色，相當於寫介面文件的同時又寫了註釋，一舉兩得
• 為Controller 層實現 Feign 呼叫介面提供更好的服務

常見問題

使用Swagger時由於Swagger會設定model屬性的預設值為空字串，但是在解析過程中只對 null 進行了判斷而沒有對 "" 空字串進行判斷，導致測試時出現許多莫名奇妙的
java.lang. NumberFormatException: For input string: ""

解決辦法:

首先排除swagger2中 swagger-models-1.5.20 版本的依賴

<dependency>

    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>

</dependency>

然後新增 1.5.21 版本，該版本已解決只判斷 null 不判斷 "" 的問題

<dependency>

    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>

</dependency>