## 一、為什么要發布API接口文檔 當下很多公司都采取前后端分離的開發模式，前端和后端的工作由不同的工程師完成。在這種開發模式下，維護一份及時更新且完整的API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是后端開發人員使用word編寫的，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式，下面我們就來了解一下它的優點： * 代碼變，文檔變。只需要少量的注解，Swagger 就可以根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。 * 跨語言性，支持 40 多種語言。 * Swagger UI 呈現出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用，省去了準備復雜的調用參數的過程。 * 還可以將文檔規范導入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創建自動化測試。 ## 二、整合swagger2生成文檔 網上有一些國內的開發者開發的`spring-boot-starter-swagger`,這個實際上不是swagger官方開發的，但是我嘗試用過，實際用起來還不錯。有小伙伴告訴我文章中更新為這個，由于我不能保證這個`spring-boot-starter-swagger`開發者的持續版本測試及更新能力，所以我就不為大家介紹這種了。大家如果喜歡用這個，可以自行去學習（和本文介紹的內容大同小異）。但是記住這不是官方提供的集成方案。 > 另外說一點，如果是個人開發的應該叫做：`swagger-xxxx-spring-boot-starter`，官方提供的才能命名為：`spring-boot-starter-swagger`。雖然這不是硬性要求，但這是spring boot官方建議開發者普遍遵循的規范。大家在自己開發spring boot應用集成包的時候要注意這點，不要給他人造成誤導！ 首先通過maven坐標引入swagger相關的類庫。 ~~~ <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> ~~~ 然后通過java Config對Swagger2進行配置。 ~~~ @Configuration @EnableSwagger2 public class Swagger2 { private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger構建api文檔") .description("簡單優雅的restfun風格") .termsOfServiceUrl("http://www.zimug.com") .version("1.0") .build(); } @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //掃描basePackage包下面的“/rest/”路徑下的內容作為接口文檔構建的目標 .apis(RequestHandlerSelectors.basePackage("com.zimug.bootlaunch")) .paths(PathSelectors.regex("/rest/.*")) .build(); } } ~~~ * @EnableSwagger2 注解表示開啟SwaggerAPI文檔相關的功能 * 在apiInfo方法中配置接口文檔的title(標題)、描述、termsOfServiceUrl（服務協議）、版本等相關信息 * 在createRestApi方法中，basePackage表示掃描哪個package下面的Controller類作為API接口文檔內容范圍 * 在createRestApi方法中，paths表示哪一個請求路徑下控制器映射方法，作為API接口文檔內容范圍 集成完成之后，做一下訪問驗證：[http://localhost:8888/swagger-ui.html](http://localhost:8888/swagger-ui.html)，如下：  swagger不僅提供了靜態的接口文檔的展示，還提供了執行接口方法測試的功能。在下圖中填入接口對應的參數，點擊“try it out"就可以實現接口請求的發送與響應結果的展示。  ## 三、書寫swagger注解 通常情況下Controller類及方法書寫了swagger注解，就不需要寫java注釋了。但是筆者從來幾乎都不寫swagger注解，也就是說本小節（三、書寫swagger注解）所講的內容筆者從來都不用。因為一個成熟的團隊，前端人員根據英文方法的名稱和參數名稱就能知道方法的作用，前提是代碼開發者認真的為接口及參數起英文名。通過團隊內推廣RESTful接口的設計原則和良好的統一的交互規范（本專欄之前已經介紹過），就能知道響應結果的含義。這也是一種“約定大于配置”的體現。 當然，如果你的團隊沒有“約定“，那么就需要“配置”來做文檔說明。我通常把這個過程叫做“為接口功能添加注釋”。寫法如下： ~~~ @ApiOperation(value = "添加文章", notes = "添加新的文章", tags = "Article",httpMethod = "POST") @ApiImplicitParams({ @ApiImplicitParam(name = "title", value = "文章標題", required = true, dataType = "String"), @ApiImplicitParam(name = "content", value = "文章內容", required = true, dataType = "String"), @ApiImplicitParam(name = "author", value = "文章作者", required = true, dataType = "String") }) @ApiResponses({ @ApiResponse(code=200,message="成功",response=AjaxResponse.class), }) @PostMapping("/article") public @ResponseBody AjaxResponse saveArticle( @RequestParam(value="title") String title, //參數1 @RequestParam(value="content") String content,//參數2 @RequestParam(value="author") String author,//參數3 ) { ~~~ swagger注釋添加完成之后，接口文檔變成如下的樣子（含有中文說明）：  ApiModel注解的用法 ~~~ @ApiModel(value = "通用響應數據結構類") public class AjaxResponse { @ApiModelProperty(value="請求是否處理成功") private boolean isok; //請求是否處理成功 @ApiModelProperty(value="請求響應狀態碼",example="200、400、500") private int code; //請求響應狀態碼（200、400、500） @ApiModelProperty(value="請求結果描述信息") private String message; //請求結果描述信息 @ApiModelProperty(value="請求結果數據") private Object data; //請求結果數據（通常用于查詢操作） } ~~~ 頁面顯示結果  雖然筆者自己從來都不寫swagger注解，但不排除有的團隊覺得可以用，所以還是詳細介紹一下: ~~~ @Api：用在Controller控制器類上 屬性tags="說明該類的功能及作用" @ApiOperation：用在Controller控制器類的請求的方法上 value="說明方法的用途、作用" notes="方法的備注說明" @ApiImplicitParams：用在請求的方法上，表示一組參數說明 @ApiImplicitParam：請求方法中參數的說明 name：參數名 value：參數的漢字說明、解釋、用途 required：參數是否必須傳，布爾類型 paramType：參數的類型，即參數存儲位置或提交方式 · header --> Http的Header攜帶的參數的獲取：@RequestHeader · query --> 請求參數的獲取：@RequestParam （如上面的例子） · path（用于restful接口）--> 請求參數的獲取：@PathVariable · body（不常用） · form（不常用） dataType：參數類型，默認String，其它值dataType="Integer" defaultValue：參數的默認值 @ApiResponses：用在控制器的請求的方法上，對方法的響應結果進行描述 @ApiResponse：用于表達一個響應信息 code：數字，例如400 message：信息，例如"請求參數沒填好" response：響應結果封裝類，如上例子中的AjaxResponse.class @ApiModel：value=“通常用在描述@RequestBody和@ResponseBody注解修飾的接收參數或響應參數實體類” @ApiModelProperty：value="實體類屬性的描述" ~~~ ## 四、生產環境下如何禁用swagger2 我們的文檔通常是在團隊內部觀看及使用的，不希望發布到生產環境讓用戶看到。 * 禁用方法1：使用注解@Profile({"dev","test"}) 表示在開發或測試環境開啟，而在生產關閉。（推薦使用，如果你不了解Profile是什么，本專欄后面的章節將有介紹，您也可以先自己了解一下） * 禁用方法2：使用注解@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 然后在測試配置或者開發配置中 添加 swagger.enable = true 即可開啟，生產環境不填則默認關閉Swagger. 更多使用細節可以參考： [https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html](https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html)