首先，老規矩，我們在接觸新事物的時候, 要對之前學習和了解過的東西做一個總結。
01
痛 苦
不做、不行
之前，前后端分離的系統由前端和后端不同的編寫，我們苦逼的后端工程師會把自己已經寫完的API接口，寫一個接口文檔給到我們前端工程師，前端工程師拿到接口文檔之后，根據接口文檔規定的URL、請求方式(POST或GET)、請求參數、返回結果(成功或失敗，失敗時，返回的狀態分別代表什么意思)，來對接我們后端提供的API接口，如果提供的接口文檔有問題，那么同樣的，前端對接時，也會出現問題，前端會說是后端提供的接口文檔的問題，后端覺得我可能程序更新了，沒有及時更新接口文檔。其實，不管是前端還是后端，都希望有一個好的接口文檔，能隨着程序的迭代不斷更新的接口文檔。
而寫接口文檔這種沒有技術含量又苦惱的事兒，對於后端來說無疑是噩夢一般，API接口少，沒幾個，可能半個點一個點就完事兒了，如果API接口很多，比如說整個訂單系統的接口，寫接口文檔這種事兒可能會耗上一天，兩天，甚至三天，最后寫完還不一定是對的，那個痛啊。
02
邂 逅
有痛點、拋出來
之前寫API文檔的方式各種各樣，wiki、word、excel、text等等各種方式，萬物皆可盤。
比如word：
對，word要把目錄給人家定義好，要不會被噴的。
再比如excel：
還有text：
千篇一律， 能不能再亂一點，前端已經提這40米的大砍刀在向你走來。
有沒有自動生成API文檔的插件呢？答：有，還自帶各種插件
關於SwaggerSwagger是一個功能強大且易於使用的API開發人員工具套件，適用於團隊和個人，可在整個API生命周期（從設計和文檔到測試和部署）中進行開發。
Swagger由開放源代碼，免費和市售工具共同組成，它使任何人（從技術工程師到街頭智能產品經理）都可以構建每個人都喜歡的驚人API。
Swagger由SmartBear Software構建，后者是團隊軟件質量工具的領導者。SmartBear落后於軟件領域的一些知名公司，包括Swagger，SoapUI和QAComplete。
在Swagger官網上提供了幾種工具，可以通過集成的方式來實現我們想要的效果。
Swagger Inspector:類似postman的一種API調試工具，可以點擊URL，查看如何使用。https://swagger.io/docs/swagger-inspector/how-to-use-swagger-inspector/。
Swagger Codegen:是一個開源代碼生成器，可直接從Swagger定義的RESTful API構建服務器存根和客戶端SDK。Swagger Codegen的源代碼可以在GitHub中找到，點擊URL，查看如何使用。https://swagger.io/docs/open-source-tools/swagger-codegen/。
Swagger Editor:是一個開源編輯器，用於設計，定義和記錄Swagger規范中的RESTful API，點擊URL查看如何使用，https://swagger.io/docs/open-source-tools/swagger-editor/
Swagger UI:提供了一個可視化的UI頁面展示描述文件。接口的調用方、測試、項目經理等都可以在該頁面中對相關接口進行查閱和做一些簡單的接口請求。該項目支持在線導入描述文件和本地部署UI項目，點擊URL查看如何使用，https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/
03
接 觸
收入囊中
Swagger是什么我們已經介紹完了，下面我們通過代碼示例來講解如何與Springboot結合使用。
1、引入Swagger相關jar包(Springboot相關jar自行引入)
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、創建啟動類，設置啟動參數，首先創建一個class，命名為SwaggerApplication，其中managerPackage為Swagger要管理的包目錄，比如com.user.api.controller，從header獲取參數名為Authorization的值，可以用於驗證權限(如果顯示不完整請左右滑動查看全部)。
1 /**
2 * Swagger2配置類
3 * 在與spring boot集成時，放在與Application.java同級的目錄下。
4 * 通過@Configuration注解，讓Spring來加載該類配置。
5 * 再通過@EnableSwagger2注解來啟用Swagger2。
6 */
7 @Configuration
8 @EnableSwagger2 9 public class SwaggerApplication{ 10 11 @Value(value = "${swagger.manager.package}") 12 private String managerPackage; 13 14 /** 15 * 創建API應用 16 * apiInfo() 增加API相關信息 17 * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現， 18 * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。 19 * 20 * @return 21 */ 22 @Bean 23 public Docket createRestApi(){ 24 ParameterBuilder aParameterBuilder = new ParameterBuilder(); 25 aParameterBuilder 26 .parameterType("header") //參數類型支持header, cookie, body, query etc 27 .name("Authorization") //參數名 28 .defaultValue("Authorization") //默認值 29 .description("token") 30 .modelRef(new ModelRef("string"))//指定參數值的類型 31 .required(false).build(); //非必需，這里是全局配置，然而在登陸的時候是不用驗證的 32 List<Parameter> aParameters = new ArrayList<Parameter>(); 33 aParameters.add(aParameterBuilder.build()); 34 return new Docket(DocumentationType.SWAGGER_2) 35 .groupName("v1") 36 .select() 37 .apis(RequestHandlerSelectors.basePackage(basePackage)) 38 .paths(PathSelectors.any()) 39 .build() 40 .apiInfo(apiInfo()) 41 .globalOperationParameters(aParameters); 42 } 43 44 public ApiInfo apiInfo(){ 45 return new ApiInfoBuilder() 46 .title("用戶管理API接口文檔") 47 .description("用戶管理API接口文檔") 48 .termsOfServiceUrl("") 49 .contact("sunf") 50 .version("1.0") 51 .build(); 52 } 53 }
3、添加實體類引用，PS：引用只添加DTO、VO，Entity不需要，class頭注解@ApiModel，申明該類被Swagger解析，@ApiModelProperty聲明各字段屬性的含義。
1 @ApiModel(description = "用戶信息")
2 @Data 3 public class Users { 4 5 @ApiModelProperty(value = "用戶ID") 6 private String id; 7 @ApiModelProperty(value = "用戶姓名") 8 private String userName; 9 @ApiModelProperty(value = "年齡") 10 private String age; 11 @ApiModelProperty(value = "性別") 12 private String sex; 13 @ApiModelProperty(value = "地址") 14 private String address; 15 @ApiModelProperty(value = "電話") 16 private String phone; 17 18 }
4、聲明Controller，暴漏API接口，如果一個接口沒有聲明明確的調用方式(POST或GET)method = RequestMethod.POST，Swagger默認會把所有的調用方式都列出來。
@RestController
@RequestMapping("/user") @Api(value = "用戶相關接口",description = "用戶信息") public class UserController { @Autowired private UserService userService; /** * 獲取用戶詳情 * @param userId * @return */ @ApiOperation(value = "獲取用戶詳情", notes = "根據用戶ID獲取用戶詳情") @RequestMapping(value = "/get",method = RequestMethod.POST) public Users get(String userId){ return userService.get(userId); } /** * 獲取所有用戶 * @return */ @ApiOperation(value = "獲取所有用戶", notes = "獲取所有用戶列表") @RequestMapping(value = "/getUserAllList",method = RequestMethod.POST) public List<Users> getUserAllList(){ return userService.getUserAllList(); } }
PS:未指定訪問方式是這樣的
5、到此Swagger的配置基本完成，啟動Springboot的服務，訪問Swagger內置的web頁面，可以看到我們暴漏的所有API和調用方式，訪問地址：http://localhost:8081/swagger-ui.html
6、點擊獲取用戶詳情的接口，try it out ,可以針對此接口進行訪問調試，點擊Model可以查看用戶實體
7、如果是頁面樣式不滿意，我們可以自定義頁面樣式，現在github已經有道友分享了自定義的ui，如何使用請查看，https://github.com/caspar-chen/swagger-ui-layer，下圖是新的UI，是不是你的菜。
小結：Swagger，就是把相關的信息存儲在它定義的描述文件里面（yml或json格式），再通過維護這個描述文件可以去更新接口文檔，以及生成各端代碼。而Springfox-swagger,則可以通過掃描代碼去生成這個描述文件，連描述文件都不需要再去維護了。所有的信息，都在代碼里面了。代碼即接口文檔，接口文檔即代碼。
微信掃一掃關注我，分享給其他人，一起成長
