@[toc]
簡介
優(yōu)點(diǎn)
后端根據(jù)swagger語法川蒙，自動(dòng)生成漂亮規(guī)范的接口文檔庙睡。
做交互測試。
劣勢
侵入式的揪漩，影響程序運(yùn)行旋恼，尤其是傳參的時(shí)候。
注意
swagger 分1.2版本和2.0版本奄容，差異較大冰更。swagger1.2 即 swagger-ui ； swagger2.0 即 springfox-swagger 昂勒。本文介紹的使用方式是新的版本蜀细，即 springfox-swagger 。
發(fā)布生產(chǎn)戈盈，關(guān)閉swagger奠衔，以防泄漏項(xiàng)目接口文檔谆刨，被攻擊
引入swagger組件
pom.xml中加入
<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>
代碼實(shí)戰(zhàn)
我看很多博主說swagger的配置代碼要和項(xiàng)目啟動(dòng)文件在同級目錄，即如下
但是归斤，移入config目錄下痊夭，經(jīng)過測試，也是正常的脏里，那這樣就看個(gè)人習(xí)慣了她我。
DemoApplication.java
package com.example;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//通過 @Configuration 注解，讓 Spring 來加載該類配置迫横。
//再通過 @EnableSwagger2 注解來啟用 Swagger2番舆。
@Configuration
@EnableSwagger2
public class DemoSwagger {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 指定要掃描的包路徑
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("項(xiàng)目api文檔")
.description("swagger接入教程")
.version("1.0")
.build();
}
}
因?yàn)橹耙呀?jīng)配置好了spring security，所以瀏覽器網(wǎng)址中輸入 http://localhost:8080/swagger-ui.html 后员淫，會(huì)被攔截住合蔽，輸入之前配置好的用戶密碼后，效果如下所示介返；
因?yàn)橹皽y試用戶登錄拴事，用戶權(quán)限，所以controller里面已經(jīng)有了一些接口方法圣蝎，但是就讓它這樣默認(rèn)刃宵，顯然用戶體驗(yàn)不好，所以在之前的userController里繼續(xù)加上swagger的注解徘公。
@Api：用在類上牲证，說明該類的作用。
@ApiOperation：說明該方法的作用关面。
具體而更細(xì)致的注解參見官方文檔 常用注解說明 坦袍。
UserController.java
package com.example.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
@RequestMapping("user")
@Api(value = "用戶模塊說明", description = "提供用戶的增、刪等太、改捂齐、查")
public class UserController {
@RequestMapping(value = "/addUser", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "添加用戶", notes = "放一些信息，供測試判斷")
String addUser() {
return "這是添加用戶Ｋ趼铡５煲恕！";
}
@RequestMapping(value = "/deleteUser", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "刪除用戶", notes = "放一些信息瞻想，供測試判斷")
String deleteUser() {
return "這是刪除用戶Ｑ拐妗！蘑险！";
}
@RequestMapping("/updateUser")
@ResponseBody
@ApiOperation(value = "修改用戶", notes = "放一些信息滴肿，供測試判斷")
String updateUser() {
return "這是修改用戶！５杵嘴高！";
}
@RequestMapping(value = "/findAllUsers", method = RequestMethod.PUT)
@ResponseBody
@ApiOperation(value = "查詢用戶", notes = "放一些信息竿音，供測試判斷")
String findAllUsers() {
return "這是查詢用戶：褪骸Ｋ┩浴！";
}
}
效果圖如下
具體打開某一條柴信，如下
很明顯套啤，有了中文注釋，文檔可讀性更強(qiáng)随常。
要說明的是潜沦，平時(shí)寫 @RequestMapping 注解的時(shí)候，我通常會(huì)簡寫绪氛，如上demo中的修改用戶方法唆鸡。但是swagger是侵入式的，如果未指定 RequestMethod 類型枣察，就會(huì)把一大堆都列出來争占，如GET，HEAD序目，POST臂痕，PUT，DELETE猿涨，OPTIONS握童，PATCH ，而其他指定好的叛赚，則是一條澡绩。
