Swagger2生成RESTful API
文章内容來自于:http://www.spring4all.com/article/251,作者:程式員DD
文章主要用于自己學習SpringBoot,友善以後的查詢
如何使用Swagger2:
1.添加pom依賴:
<!--添加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>
2.在與Application.java同級目錄下建立Swagger.java:
@Configuration //通過@Configuration注解,讓Spring來加載該類配置
@EnableSwagger2 //通過@EnableSwagger2注解來啟用Swagger2
public class Swagger2 {
@Bean
public Docket createRestApi(){//通過createRestApi()函數建立Docket的Bear之後
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //apiInfo()用來建立Api的基本資訊(這些資訊會展現在文檔頁面中)
.select() //select()函數傳回一個ApiSelectorBuilder執行個體用來控制哪些接口暴露給Swagger來展現
.apis(RequestHandlerSelectors.basePackage("com.chimm.web")) //本例采用指定掃描的包路徑來定義
.paths(PathSelectors.any()) //Swagger會掃描該包下的所有Controller定義的API,并産生文檔内容(除了被@ApiIgnore定義的請求)
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2建構RESTful APIs")
.description("更多Spring boot相關文章請關注:http://blog.didispace.com/")
.termsOfServiceUrl("https://blog.csdn.net/qq_36704469/article/details/80227353")
.contact("吃茫茫")
.version("1.0")
.build();
}
如上代碼所示,通過
@Configuration
注解,讓Spring來加載該類配置。再通過
@EnableSwagger2
注解來啟用Swagger2。
再通過
createRestApi()
函數建立
Docket
的Bean之後,
apiInfo()
用來建立該Api的基本資訊(這些基本資訊會展現在文檔頁面中)。
select()
函數傳回一個
ApiSelectorBuilder
執行個體用來控制哪些接口暴露給Swagger來展現,本例采用指定掃描的包路徑來定義,Swagger會掃描該包下所有Controller定義的API,并産生文檔内容(除了被
@ApiIgnore
指定的請求)。
3.添加文檔内容
@RestController
@RequestMapping("/users") //通過這裡配置使下面的映射都在/users下。可去除
public class UserController {
/* 建立【線程安全】的Map(悲觀鎖)
缺點:從鎖的角度來看,Collections.synchronizedMap直接鎖住了
盡可能大的代碼塊,性能會比較差
*/
static Map<Long,User> users = Collections.synchronizedMap(new HashMap<Long, User>());
@ApiOperation(value = "擷取使用者清單",notes = "")
@RequestMapping(value = "/",method = RequestMethod.GET)
public List<User> getUserList(){
// 處理"/users"的GET請求,用來擷取使用者清單
// 還可以通過@RequestParam從頁面中傳遞參數來進行查詢條件或者翻頁資訊的傳遞
List<User> userList = new ArrayList<>(users.values());
return userList;
}
@ApiOperation(value = "建立使用者",notes = "根據User對象建立使用者")
@ApiImplicitParam(name = "user",value = "使用者詳細實體user",required = true,dataType = "User")
@RequestMapping(value = "/",method = RequestMethod.POST)
public String postUser(@ModelAttribute User user){
// 處理"/users"的POST請求,用來建立User
// 除了@ModelAttribute綁定參數之外,還可以通過@RequestParam從頁面傳遞參數
users.put(user.getId(),user);
return "success";
}
@ApiOperation(value = "擷取使用者詳細資訊",notes = "根據url的id來擷取使用者詳細資訊")
@ApiImplicitParam(name = "id",value = "使用者ID",required = true,dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
public User getUser(@PathVariable("id") Long id){
// 處理"/users/{id}的GET請求,用來擷取url中id值的User資訊"
// url中的id可通過@PathVariable綁定到函數的參數中
return users.get(id);
}
@ApiOperation(value = "更新使用者詳細資訊",notes = "根據url的id來指定更新對象,并根據傳過來的user資訊來更新使用者詳細資訊")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "使用者ID",required = true,dataType = "Long"),
@ApiImplicitParam(name = "user",value = "使用者詳細實體user",required = true,dataType = "User")
})
@RequestMapping(value = "/{id}",method = RequestMethod.PUT)
public String putUser(@PathVariable Long id,@ModelAttribute User user){
// 處理"/users/{id}"的PUT請求,用來更新User資訊
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id,u);
return "success";
}
@ApiOperation(value = "删除使用者",notes = "根據url的id來指定删除對象")
@ApiImplicitParam(name = "id",value = "使用者ID",required = true,dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id){
// 處理"/users/{id}"的DELETE請求,用來删除User
users.remove(id);
return "success";
}
}
完成上述代碼添加上,啟動Spring Boot程式,通路:http://localhost:8080/swagger-ui.html。就可以檢視API文檔了。如下圖