添加Swagger2依賴
在pom.xml中加入Swagger2的依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
創(chuàng)建Swagger2配置類
在Application.java同級(jí)創(chuàng)建Swagger2的配置類Swagger2狰右。
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
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("你自己的外部接口包名稱"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("詞網(wǎng)Neo4j RESTful APIs")
.description("The Neo4j RESTful APIs description/")
.termsOfServiceUrl("")
.contact("李慶海")
.version("5.0")
.build();
}
}
添加文檔內(nèi)容
在完成了上述配置后逢净，其實(shí)已經(jīng)可以生產(chǎn)文檔內(nèi)容恍涂，但是這樣的文檔主要針對(duì)請(qǐng)求本身嫌套，而描述主要來(lái)源于函數(shù)等命名產(chǎn)生疏旨，對(duì)用戶并不友好，我們通常需要自己增加一些說(shuō)明來(lái)豐富文檔內(nèi)容堤撵。
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
/**
* 系統(tǒng)用戶Controller
*
* @author 李慶海
*
*/
@Api(value = "系統(tǒng)用戶接口", tags = "系統(tǒng)管理")
@RestController
@RequestMapping("/v3/edu/users")
public class UserController {
@Autowired
private UserService userService;
/**
* 添加用戶价脾，注冊(cè)
*
* @param loginName
* 登錄賬號(hào)
* @param userName
* 用戶名稱
* @param password
* 登錄密碼
* @param roleId
* 用戶角色
* @return
* @throws ResourceExistsException
*/
@ApiOperation(value = "添加用戶")
@PostMapping("/")
public JsonResult create(
@ApiParam(name = "loginName", value = "登錄賬號(hào)", required = true) @RequestParam(required = true) @RequestBody String loginName,
@ApiParam(name = "userName", value = "用戶名稱", required = true) @RequestParam(required = true) @RequestBody String userName,
@ApiParam(name = "password", value = "登錄密碼", required = true) @RequestParam(required = true) @RequestBody String password,
@ApiParam(name = "roleId", value = "用戶角色編號(hào)", required = true) @RequestParam(required = true) @RequestBody String roleId)
throws ResourceExistsException {
boolean exists = this.userService.exists(loginName);
if (exists) {
throw new ResourceExistsException(loginName);
}
User user = userService.create(loginName, password, userName, roleId);
return new JsonResult(user);
}
}
查看API
啟動(dòng)Spring Boot程序，訪問(wèn)：http://localhost:8080/swagger-ui.html
微信截圖_20180106154957.png
API文檔訪問(wèn)與調(diào)試
Swagger除了查看接口功能外蝶俱，還提供了調(diào)試測(cè)試功能班利，我們可以點(diǎn)擊上圖中右側(cè)的Model Schema（黃色區(qū)域：它指明了數(shù)據(jù)結(jié)構(gòu)），此時(shí)Value中就有了user對(duì)象的模板榨呆，我們只需要稍適修改罗标，點(diǎn)擊下方Try it out！按鈕积蜻，即可完成了一次請(qǐng)求調(diào)用闯割！可以通過(guò)幾個(gè)GET請(qǐng)求來(lái)驗(yàn)證之前的POST請(qǐng)求是否正確。
