通常我們要構(gòu)建API 服務(wù)厉颤，自然少不了文檔，但由于API與文檔的分離使得我們每次對(duì)API進(jìn)行的更改都需要去同步文檔，稍有紕漏難免就會(huì)出現(xiàn)調(diào)用的異常归榕，而編寫(xiě)、同步文檔通常是比較繁瑣無(wú)趣的事≈ㄉ妫現(xiàn)在得益于Spring Boot 與Swagger刹泄，我們不但可以極速的搭建REST外里、RESTful風(fēng)格的API服務(wù)并且還可以生成優(yōu)美、強(qiáng)大的在線或離線API文檔特石。
-
引入Maven依賴
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.1.RELEASE</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>
</dependencies>
-
創(chuàng)建Application主類
package example;//注意包結(jié)構(gòu)
@SpringBootApplication
public class Application {
public static void main(String[] args) throws Exception {
SpringApplication.run(Application.class, args);
}
}
-
創(chuàng)建Swagger配置類
package example.config;//注意包結(jié)構(gòu)
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("example.web.controller"))//要掃描的API(Controller)基礎(chǔ)包
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2 UI構(gòu)建API文檔")
.contact("土豆")
.version("1.0")
.build();
}
}
-
創(chuàng)建RestController 構(gòu)建一個(gè)簡(jiǎn)單計(jì)算服務(wù)API
package example.web.controller;//注意包結(jié)構(gòu)
@Api(value = "計(jì)算服務(wù)",description="簡(jiǎn)單的計(jì)算服務(wù)盅蝗，提供加減乘除運(yùn)算API")
@RestController
@RequestMapping("/compute")
public class ComputeController {
@ApiOperation("加法運(yùn)算")
@PostMapping("/add")
public Double add(@RequestParam Double a, @RequestParam Double b) {
return a + b;
}
@ApiOperation("減法運(yùn)算")
@PostMapping("/sub")
public Double sub(@RequestParam Double a, @RequestParam Double b) {
return a - b;
}
@ApiOperation("乘法運(yùn)算")
@PostMapping("/mul")
public Double mul(@RequestParam Double a, @RequestParam Double b) {
return a * b;
}
@ApiOperation("除法運(yùn)算")
@PostMapping("/div")
public Double div(@ApiParam("被除數(shù)")@RequestParam Double a, @ApiParam("除數(shù)")@RequestParam Double b) {
return a / b;
}
}
@Api注解用來(lái)表述該服務(wù)的信息，如果不使用則顯示類名稱.
@ApiOperation注解用于表述接口信息
@ApiParam注解用于描述接口的參數(shù)
通過(guò)上面幾步我們已經(jīng)成功構(gòu)建了一個(gè)具備加減乘除的計(jì)算服務(wù)API姆蘸，并且已經(jīng)擁有一份不錯(cuò)的在線文檔了墩莫，現(xiàn)在我們來(lái)啟動(dòng)它，執(zhí)行mvn spring-boot:run逞敷，或直接運(yùn)行Application.main()狂秦。
啟動(dòng)成功后，訪問(wèn)http://localhost:8080/swagger-ui.html推捐，便可以看到我們剛才構(gòu)建的計(jì)算服務(wù)的API文檔了裂问。
Swagger UI不僅僅是文檔，還提供了在線API調(diào)試的功能牛柒，我們可以調(diào)試下我們的除法運(yùn)算API堪簿。
點(diǎn)擊Try it out！后可以看到我們成功的調(diào)用了除法運(yùn)算API并獲得了正確的響應(yīng)椭更。
-
創(chuàng)建RESTful 風(fēng)格的API及文檔
下面我們以用戶的增刪改查服務(wù)為例
1.創(chuàng)建Model
package example.model;//注意包結(jié)構(gòu)
public class User {
private Long id;
private String username;
private Integer age;
//省略getter畏腕、setter方法
}
2.創(chuàng)建RestController
package example.web.controller;//注意包結(jié)構(gòu)
@RestController
@RequestMapping("/user")
@Api(value = "用戶服務(wù)",description = "提供RESTful風(fēng)格API的用戶的增刪改查服務(wù)")
public class UserController {
//模擬DAO層
private final Map<Long, User> repository = new HashMap<Long, User>();
@PostMapping
@ApiOperation("添加用戶")
public Boolean add(@RequestBody User user) {
repository.put(user.getId(), user);
return true;
}
@DeleteMapping("/{id}")
@ApiOperation("通過(guò)ID刪除用戶")
public Boolean delete(@PathVariable Long id) {
repository.remove(id);
return true;
}
@PutMapping
@ApiOperation("更新用戶")
public Boolean update(@RequestBody User user) {
repository.put(user.getId(), user);
return true;
}
@GetMapping("/{id}")
@ApiOperation("通過(guò)ID查詢用戶")
public User findById(@PathVariable Long id) {
return repository.get(id);
}
}
這里說(shuō)點(diǎn)題外話恋日，@GetMapping,@PostMapping,@PutMapping,@DeleteMapping 等注解是Spring MVC 4.3X版本添加的新注解，它們是對(duì)@RequestMapping注解的簡(jiǎn)化封裝谈截。
好了喻鳄，我們重新啟動(dòng)下Application，再次訪問(wèn)http://localhost:8080/swagger-ui.html，用戶服務(wù)的RESTful API文檔也已生成。
我們來(lái)嘗試調(diào)用添加用戶API增加一位用戶
成功后聚请，我們調(diào)用查詢API，來(lái)進(jìn)行查詢看時(shí)候可以返回正確的JSON數(shù)據(jù)。
-
為Model(JSON)添加注釋
為了使API的調(diào)用者能夠清晰的知道請(qǐng)求和響應(yīng)的Model中各字段的具體含義疙驾，我們需要對(duì)其添加一些簡(jiǎn)單的注釋郭毕，而Swagger也為我們提供了相應(yīng)的注解比如@ApiModel它碎、@ApiModelProperty來(lái)幫助我們解釋我們的Model，下面就是最簡(jiǎn)單的使用例子，詳細(xì)用法及更多相關(guān)注解點(diǎn)我查看~
@ApiModel("User(用戶模型)")
public class User {
@ApiModelProperty("ID")
private Long id;
@ApiModelProperty("用戶名")
private String username;
@ApiModelProperty("年齡")
private Integer age;
//省略getter扳肛、setter方法
}
這一切是不是很簡(jiǎn)單傻挂？從開(kāi)發(fā)API到構(gòu)建高逼格的API文檔完全可以用極速來(lái)形容。當(dāng)然敞峭，本文也只是展現(xiàn)了Spring Boot + Swagger的冰山一角踊谋，要了解更多細(xì)節(jié)那就快去翻閱官方文檔吧~
本示例完整代碼的GIT地址點(diǎn)擊我~
Swagger-Core文檔點(diǎn)擊我~
SpringFox文檔點(diǎn)擊我~
Spring Boot 文檔點(diǎn)擊我~
還不錯(cuò)的Spring Boot系列教程點(diǎn)擊我~
