springboot系列：SpringBoot第十一篇：springboot集成swagger2，構建優雅的Restful AP

swagger,中文“拽”的意思。它是一個功能強大的api框架，它的集成非常簡單，不僅提供了在線文檔的查閱，而且還提供了在線文檔的測試。另外swagger很容易構建restful風格的api，簡單優雅帥氣，正如它的名字。

一、引入依賴

io.springfox

springfox-swagger2

2.6.1

io.springfox

springfox-swagger-ui

2.6.1

二、寫配置類

@Configuration

@EnableSwagger2

public?class?Swagger2?{

@Bean

public?Docket?createRestApi()?{

return?new?Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("com.forezp.controller"))

.paths(PathSelectors.any())

.build();

}

private?ApiInfo?apiInfo()?{

return?new?ApiInfoBuilder()

.title("Springboot利用swagger構建api文檔")

.description("簡單優雅的restfun風格，http://blog.csdn.net/forezp")

.termsOfServiceUrl("http://blog.csdn.net/forezp")

.version("1.0")

.build();

}

}

通過@Configuration注解，表明它是一個配置類，@EnableSwagger2開啟swagger2。apiINfo()配置一些基本的信息。apis()指定掃描的包會生成文檔。

三、寫生產文檔的注解

swagger通過注解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。

·??????@Api：修飾整個類，描述Controller的作用

·??????@ApiOperation：描述一個類的一個方法，或者說一個接口

·??????@ApiParam：單個參數描述

·??????@ApiModel：用對象來接收參數

·??????@ApiProperty：用對象接收參數時，描述對象的一個字段

·??????@ApiResponse：HTTP響應其中1個描述

·??????@ApiResponses：HTTP響應整體描述

·??????@ApiIgnore：使用該注解忽略這個API

·??????@ApiError?：發生錯誤返回的信息

·??????@ApiParamImplicitL：一個請求參數

·??????@ApiParamsImplicit多個請求參數

現在通過一個栗子來說明：

package?com.forezp.controller;

import?com.forezp.entity.Book;

import?io.swagger.annotations.ApiImplicitParam;

import?io.swagger.annotations.ApiImplicitParams;

import?io.swagger.annotations.ApiOperation;

import?org.springframework.ui.ModelMap;

import?org.springframework.web.bind.annotation.*;

import?springfox.documentation.annotations.ApiIgnore;

import?java.util.*;

/**

*?用戶創建某本圖書????POST????/books/

*?用戶修改對某本圖書????PUT????/books/:id/

*?用戶刪除對某本圖書????DELETE????/books/:id/

*?用戶獲取所有的圖書?GET?/books

*??用戶獲取某一圖書??GET?/Books/:id

*?Created?by?fangzhipeng?on?2017/4/17.

*?官方文檔：http://swagger.io/docs/specification/api-host-and-base-path/

*/

@RestController

@RequestMapping(value?=?"/books")

public?class?BookContrller?{

Map?books?=?Collections.synchronizedMap(new?HashMap());

@ApiOperation(value="獲取圖書列表",?notes="獲取圖書列表")

@RequestMapping(value={""},?method=?RequestMethod.GET)

public?List?getBook()?{

List?book?=?new?ArrayList<>(books.values());

return?book;

}

@ApiOperation(value="創建圖書",?notes="創建圖書")

@ApiImplicitParam(name?=?"book",?value?=?"圖書詳細實體",?required?=?true,?dataType?=?"Book")

@RequestMapping(value="",?method=RequestMethod.POST)

public?String?postBook(@RequestBody?Book?book)?{

books.put(book.getId(),?book);

return?"success";

}

@ApiOperation(value="獲圖書細信息",?notes="根據url的id來獲取詳細信息")

@ApiImplicitParam(name?=?"id",?value?=?"ID",?required?=?true,?dataType?=?"Long",paramType?=?"path")

@RequestMapping(value="/{id}",?method=RequestMethod.GET)

public?Book?getBook(@PathVariable?Long?id)?{

return?books.get(id);

}

@ApiOperation(value="更新信息",?notes="根據url的id來指定更新圖書信息")

@ApiImplicitParams({

@ApiImplicitParam(name?=?"id",?value?=?"圖書ID",?required?=?true,?dataType?=?"Long",paramType?=?"path"),

@ApiImplicitParam(name?=?"book",?value?=?"圖書實體book",?required?=?true,?dataType?=?"Book")

})

@RequestMapping(value="/{id}",?method=?RequestMethod.PUT)

public?String?putUser(@PathVariable?Long?id,?@RequestBody?Book?book)?{

Book?book1?=?books.get(id);

book1.setName(book.getName());

book1.setPrice(book.getPrice());

books.put(id,?book1);

return?"success";

}

@ApiOperation(value="刪除圖書",?notes="根據url的id來指定刪除圖書")

@ApiImplicitParam(name?=?"id",?value?=?"圖書ID",?required?=?true,?dataType?=?"Long",paramType?=?"path")

@RequestMapping(value="/{id}",?method=RequestMethod.DELETE)

public?String?deleteUser(@PathVariable?Long?id)?{

books.remove(id);

return?"success";

}

@ApiIgnore//使用該注解忽略這個API

@RequestMapping(value?=?"/hi",?method?=?RequestMethod.GET)

public?String??jsonTest()?{

return?"?hi?you!";

}

}

通過相關注解，就可以讓swagger2生成相應的文檔。如果你不需要某接口生成文檔，只需要在加@ApiIgnore注解即可。需要說明的是，如果請求參數在url上，@ApiImplicitParam?上加paramType = “path”?。

啟動工程，訪問：http://localhost:8080/swagger-ui.html?，就看到swagger-ui:

整個集成過程非常簡單，但是我看了相關的資料，swagger沒有做安全方面的防護，可能需要我們自己做相關的工作。

四、參考資料

swagger.io

Spring Boot中使用Swagger2構建強大的RESTful API文檔

方志朋簡介：SpringCloud中國社區聯合創始人，博客訪問量突破一千萬，愛好開源，熱愛分享，活躍于各大社區，保持著非常強的學習驅動力，終身學習踐行者，終身學習受益者。目前就職于國內某家知名互聯網保險公司，擔任DEVOPS工程師，對微服務領域和持續集成領域研究較深，精通微服務框架SpringCloud

Spring Boot API

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。