上一篇我們介紹瞭如何使用Spring Boot快速構建RESTful API “Spring Boot與RESTful API ” ，本篇則介紹一個配合Spring Boot快速構建RESTful文檔的工具
由於Spring Boot具有快速開發、便捷部署的特點，很多用戶會使用Spring Boot構建RESTful API，一個RESTful接口往往對應不止一個終端，有WEB端、安卓端、IOS端等等。正因爲這樣，一個接口可能要面對多個開發人員或者團隊，爲了減少溝通來帶的時間成本，大家往往會準備一個RESTful API的文檔，但是這種文檔往往有幾個致命的問題：
- 由於接口過多，細節複雜，文檔本身構建起來就比較麻煩
- 隨着時間的推移，接口往往會修改或者廢棄，這就需要對所有調用方同步文檔，如果出現遺漏，很容易造成接口調用失敗
爲了解決以上問題，就要介紹一下Swagger2，它可以很簡單的整合到Spring Boot中，它可以組織出強大的RESTful API文檔。效果如圖：
此次以上篇文章的代碼爲例對Swagger2進行講解。
導入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>創建Swagger2類
Swagger2類需要與Application.java同級
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
//需要配置正確需要掃面的的包名
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wangxin.restapi"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構建RESTful APIs")
.description("更多Spring Boot相關文章請關注：https://my.oschina.net/wangxincj/blog/")
.termsOfServiceUrl("https://my.oschina.net/wangxincj/blog/")
.contact("老虎是個蛋蛋")
.version("1.0")
.build();
}
}
如上所示，
- 添加@Configuration註解，表示讓Spring在啓動時加載該配置
- @EnableSwagger2表示在Spring Boot中啓動Swagger2
- createRestApi方法創建Docket的Bean
- apiInfo()用來創建該API的基本信息
- ApiInfoBuilder實力來控制那些接口需要暴露給Swagger來展現
添加文檔內容註解
我們通過使用@ApiOperation註解對接口進行描述，通過@ApiImplicitParam和@ApiImplicitParams對參數進行描述
@RestController
@RequestMapping("/book")
public class BookController {
public static Map<String,Book> bookMap = new HashMap<String,Book>();
/**
* 添加一本書
* @param book
* @return
*/
@ApiOperation(value="創建一本書", notes="創建一本書")
@ApiImplicitParam(name = "book", value = "book實體bean", required = true, dataType = "Book")
@RequestMapping(value="",method = RequestMethod.POST)
public String postBook (@ModelAttribute Book book){
bookMap.put(book.getIsbn(),book);
return "SUCCESS";
}
/**
* 查詢出所有book集合
* @return
*/
@ApiOperation(value="查詢出所有book集合", notes="")
@RequestMapping(value={""},method = RequestMethod.GET)
public List<Book> getBookList (){
List<Book> bookList = new ArrayList<Book>(bookMap.values());
return bookList;
}
/**
* 根據ISBN獲取book
* @param isbn
* @return
*/
@ApiOperation(value="圖書詳細信息", notes="根據url的isbn來獲取圖書詳細信息")
@ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
@RequestMapping(value="/{isbn}",method = RequestMethod.GET)
public Book getBook(@PathVariable String isbn){
Book book = bookMap.get(isbn);
return book;
}
/**
* 更新book參數
* @param isbn
* @param book
* @return
*/
@ApiOperation(value="更新圖書詳細信息", notes="根據url的ISBN來指定更新對象，並根據傳過來的book信息來更新圖書詳細信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String"),
@ApiImplicitParam(name = "book", value = "圖書詳細實體book", required = true, dataType = "Book")
})
@RequestMapping(value="/{isbn}",method = RequestMethod.PUT)
public String putBook(@PathVariable String isbn, @ModelAttribute Book book){
Book b = bookMap.get(isbn);
b.setAuthor(book.getAuthor());
b.setName(book.getName());
bookMap.put(isbn,b);
return "SUCCESS";
}
/**
* 根據isbn刪除book
* @param isbn
* @return
*/
@ApiOperation(value="刪除圖書", notes="根據url的ISBN來指定刪除圖書")
@ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
@RequestMapping(value="/{isbn}",method = RequestMethod.DELETE)
public String deleteBook(@PathVariable String isbn){
bookMap.remove(isbn);
return "SUCCESS";
}
}
完成以上操作，我們啓動Spring Boot，訪問http://localhost:8080/swagger-ui.html，即可看到Swagger2生成的RESTful API，如下：
API調試
Swagger2不僅可以生成API文檔，還可以在線調試接口，如上圖，有兩種填寫參數方式，第一種是在Parameter列表項中有Book對象需要填寫的參數，大家可以根據實際情況填寫參數值；第二種方式我們可以點擊上圖中右側的Model Schema（黃色區域：它指明瞭Book的數據結構），此時Value中就有了book對象的模板，我們只需要稍適修改。填寫完參數點擊“Try it out!”即可完成接口請求。
相比爲這些接口編寫文檔的工作，我們增加的配置內容是非常少而且精簡的，對於原有代碼的侵入也在忍受範圍之內。因此，在構建RESTful API的同時，加入swagger來對API文檔進行管理，是個不錯的選擇。