Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調用和可視化RESTful風格的 Web 服務。總體目標是使客戶端和文件系統(tǒng)作為服務器以同樣的速度來更新。文件的方法，參數(shù)和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
1.代碼示例
1).在pom.xml文件中引入Swagger2
|
1
2
3
4
5
6
7
8
9
10
|
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> |
2).在Application同級目錄下添加Swagger2的配置類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
package com.example;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@EnableSwagger2public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2構建RESTful APIs") .description("spring boot整合swagger2") .termsOfServiceUrl("www.baidu.com") .contact("牛頭人") .version("1.0") .build(); }} |
如上代碼所示，通過 @Configuration 注解，讓Spring來加載該類配置。再通過 @EnableSwagger2 注解來啟用Swagger2。
通過 createRestApi 函數(shù)創(chuàng)建 Docket 的Bean之后， apiInfo() 用來創(chuàng)建該Api的基本信息（這些基本信息會展現(xiàn)在文檔頁面中）。 select() 函數(shù)返回一個 ApiSelectorBuilder 實例用來控制哪些接口暴露給Swagger來展現(xiàn)，本例采用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，并產生文檔內容（除了被 @ApiIgnore 指定的請求）。
3).新建User實體類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
package com.example.swagger2;public class User { private String id; private String name; public String getId() { return id; } public void setId(String id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; }} |
4).新建SwaggerDemoController類
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
package com.example.swagger2;import java.util.ArrayList;import java.util.Collections;import java.util.HashMap;import java.util.List;import java.util.Map;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiResponse;import io.swagger.annotations.ApiResponses;@RestController@RequestMapping(value="/api") @Api("SwaggerDemoController相關api")public class SwaggerDemoController { static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>()); @ApiOperation(value="獲取用戶列表", notes="") @ApiResponses({ @ApiResponse(code=400,message="請求參數(shù)沒填好"), @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對") }) @RequestMapping(value={""}, method=RequestMethod.GET) public List<User> getUserList() { List<User> r = new ArrayList<User>(users.values()); return r; } @ApiOperation(value="創(chuàng)建用戶", notes="根據(jù)User對象創(chuàng)建用戶") @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User") @ApiResponses({ @ApiResponse(code=400,message="請求參數(shù)沒填好"), @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對") }) @RequestMapping(value="", method=RequestMethod.POST) public String postUser(@RequestBody User user) { users.put(user.getId(), user); return "success"; } @ApiOperation(value="獲取用戶詳細信息", notes="根據(jù)url的id來獲取用戶詳細信息") @ApiImplicitParam(name = "id", value = "用戶ID",paramType="path", required = true, dataType = "String") @ApiResponses({ @ApiResponse(code=400,message="請求參數(shù)沒填好"), @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對") }) @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable String id) { System.out.println("id="+id); return users.get(id); } @ApiOperation(value="更新用戶詳細信息", notes="根據(jù)url的id來指定更新對象，并根據(jù)傳過來的user信息來更新用戶詳細信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID",paramType="path", required = true, dataType = "String"), @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User") }) @ApiResponses({ @ApiResponse(code=400,message="請求參數(shù)沒填好"), @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對") }) @RequestMapping(value="/{id}", method=RequestMethod.PUT) public String putUser(@PathVariable String id, @RequestBody User user) { System.out.println("id="+id); User u = users.get(id); u.setName(user.getName()); users.put(id, u); return "success"; } @ApiOperation(value="刪除用戶", notes="根據(jù)url的id來指定刪除對象") @ApiImplicitParam(name = "id", value = "用戶ID",paramType="path", required = true, dataType = "String") @ApiResponses({ @ApiResponse(code=400,message="請求參數(shù)沒填好"), @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對") }) @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable String id) { System.out.println("id="+id); users.remove(id); return "success"; }} |
說明：
@Api：用在類上，說明該類的作用
@ApiOperation：用在方法上，說明方法的作用
@ApiImplicitParams：用在方法上包含一組參數(shù)說明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面
paramType：參數(shù)放在哪個地方
header-->請求參數(shù)的獲取：@RequestHeader
query-->請求參數(shù)的獲取：@RequestParam
path（用于restful接口）-->請求參數(shù)的獲取：@PathVariable
body（不常用）
form（不常用）
name：參數(shù)名
dataType：參數(shù)類型
required：參數(shù)是否必須傳
value：參數(shù)的意思
defaultValue：參數(shù)的默認值
@ApiResponses：用于表示一組響應
@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息
code：數(shù)字，例如400
message：信息，例如"請求參數(shù)沒填好"
response：拋出異常的類
@ApiModel：描述一個Model的信息（這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景，請求參數(shù)無法使用@ApiImplicitParam注解進行描述的時候）
@ApiModelProperty：描述一個model的屬性
通過 @ApiOperation 注解來給API增加說明、通過 @ApiImplicitParams 、 @ApiImplicitParam 注解來給參數(shù)增加說明。
需要注意的是：
如果ApiImplicitParam中的phone的paramType是query的話，是無法注入到rest路徑中的，而且如果是path的話，是不需要配置ApiImplicitParam的，即使配置了，其中的value="用戶ID"也不會在swagger-ui展示出來。
具體其他的注解，查看：
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
2.測試：
啟動服務，瀏覽器輸入"http://localhost:8080/swagger-ui.html"
GET紅框：method=RequestMethod.GET
右邊紅框：@ApiOperation
parameter紅框：@ApiImplicitParams系列注解
response messages紅框：@ApiResponses系列注解
輸入參數(shù)后，點擊"try it out!"，查看響應內容：
以上所述是小編給大家介紹的spring boot整合Swagger2的示例代碼，希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會及時回復大家的。在此也非常感謝大家對服務器之家網站的支持！
原文鏈接：http://www.cnblogs.com/web424/p/6774507.html
