1快速環境搭建

pom.xml文件中添加如下內容(看清楚再復制，此處不是全部內容)

1 <properties> 2 ... 3 <swagger.version>2.2.2</swagger.version> 4 ... 5 </properties> 6 7 <dependency> 8 <groupId>io.springfox</groupId> 9 <artifactId>springfox-swagger2</artifactId> 10 <version>${swagger.version}</version> 11 </dependency> 12 <dependency> 13 <groupId>io.springfox</groupId> 14 <artifactId>springfox-swagger-ui</artifactId> 15 <version>${swagger.version}</version> 16 </dependency>

在config目錄中新建swagger的配置文件swaggerConfig.java

1 @EnableSwagger2 2 @Configuration 3 public class SwaggerConfig { 4 5 @Bean 6 public Docket createRestApi() { 7 return new Docket(DocumentationType.SWAGGER_2) 8 .apiInfo(apiInfo()) 9 .select() 10 .apis(RequestHandlerSelectors.basePackage("com"))//掃描com路徑下的api文檔 11 .paths(PathSelectors.any())//路徑判斷 12 .build(); 13 } 14 15 private ApiInfo apiInfo() { 16 return new ApiInfoBuilder() 17 .title("《----我是title-----》")//標題 18 .description("《-----我是描述----》：http://www.google.com.hk")//描述 19 .termsOfServiceUrl("http://www.google.com.hk")//（不可見）條款地址 20 .contact(new Contact("zz","google.com.hk","123@qq.com"))//作者信息 21 .version("6.6.6")//版本號 22 .build(); 23 } 24 25 }

新建實體類User，基本字段如下

1 @ApiModel(value = "User得實體，----》",reference = "我是參考") 2 public class User { 3 4 @ApiParam(value = "姓名--------------",required = true) 5 private String name; 6 //在swagger-ui.html#頁面中如果返回User，ModelModel Schema選項卡可見 7 @ApiModelProperty(value = "id",dataType = "String") 8 private String id; 9 //在http://localhost:8080/v2/api-docs最后一行的實體可見 10 @ApiModelProperty(value = "年齡----------",required = true) 11 private Integer age; 12 13 ...此處省略set和get方法 14 }

在controller包立新建TestController，內容如下

1 @Api(value = "API - VehiclesController", description = "用戶接口詳情") 2 @RestController 3 @RequestMapping("/test") 4 public class TestController { 5 6 static Map<String, User> users = Collections.synchronizedMap(new HashMap<String,User>()); 7 8 9 @ApiOperation(value="獲取用戶列表", notes="") 10 @ApiResponses(value = { 11 @ApiResponse(code = 200, message = "Successful — 請求已完成"), 12 @ApiResponse(code = 400, message = "請求中有語法問題，或不能滿足請求"), 13 @ApiResponse(code = 401, message = "未授權客戶機訪問數據"), 14 @ApiResponse(code = 404, message = "服務器找不到給定的資源；文檔不存在"), 15 @ApiResponse(code = 500, message = "服務器不能完成請求")} 16 ) 17 @RequestMapping(value={""}, method= RequestMethod.GET) 18 public List<User> getUserList() { 19 List<User> r = new ArrayList<User>(users.values()); 20 return r; 21 } 22 23 ....此處省略n行代碼 24 }

瀏覽改地址，訪問主頁面：http://localhost:8080/swagger-ui.html#?
瀏覽改地址，訪問sagger專有jsonAPI：?http://localhost:8080/v2/api-docs

2常用注釋描述

3全部注釋列表

@Api?
Api 標記可以標記一個Controller類做為swagger 文檔資源，使用方式

@Api?
Api 標記可以標記一個Controller類做為swagger 文檔資源，使用方式

屬性名稱備注

value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置為true 將在文檔中隱藏

---

@ApiOperation每一個url資源的定義,使用方式

屬性名稱備注

value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置為true 將在文檔中隱藏
response	返回的對象
responseContainer	這些對象是有效的 “List”, “Set” or “Map”.，其他無效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的狀態碼 默認 200
extensions	擴展屬性

---

@ApiParam標記?
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)

屬性名稱備注

name	屬性名稱
value	屬性值
defaultValue	默認屬性值
allowableValues	可以不配置
required	是否屬性必填
access	不過多描述
allowMultiple	默認為false
hidden	隱藏該屬性
example	舉例子

---

@ApiImplicitParam對容器的描述

屬性名稱備注

name	屬性名稱
value	屬性值
defaultValue	默認值
allowableValues	可以不可配置
required	是否屬性必填
access	不可過多描述
allowMutiple	默認為false
dataType	數據類型
paramType	參數類型

---

@ApiResponse

屬性名稱備注

code	http的狀態碼
message	描述
response	默認響應類 Void
reference	參考ApiOperation中配置
responseHeaders	參考 ResponseHeader 屬性配置說明
responseContainer	參考ApiOperation中配置

---

@ResponseHeader(name=”head1”,description=”response head conf”)

屬性名稱備注

name	響應頭名稱
description	頭描述
response	默認響應類 Void
responseContainer	參考ApiOperation中配置

4文檔編寫規范建議

• entity的描述

@ApiModel(description = “我是描述”,value = “用戶”)?
對實體的描述

description：在v2/api-docs的實體看到描述，?
value的值在@ApiImplicitParam注解中的dataType可用，

@ApiModelProperty(value = “用戶姓名”,required = true,dataType = “String”)?
private String name;?
對字段的描述

value：1，入參和出參的ModelModel Schema選項卡可見，2，在v2/api-docs的實體字段描述可見?
required：該屬性是否必填寫?
dataType:該字段的數據類型

• controller的描述

@Api(value = “API”, description = “用戶接口詳情”,tags=”A”)?
對controler的描述

value:訪問某個controller的url的根路徑值?
description：對于該controller的的大概描述?
tags:把api接口進行分分組

@ApiOperation(value = “獲取用戶詳細信息”, notes = “根據url的id來獲取用戶詳細信息”,httpMethod =”GET”)?
對該方法的描述

value:主頁面中對該接口的描述，位置在接口的最右邊?
notes：點開接口后，第一段描述。?
httpMethod:HTTP請求的動作名，可選值有：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。

@ApiImplicitParam(name = “id”, value = “用戶ID”, required = true, dataType = “String”, paramType = “path”)?
對參數的描述，如果多個參數需要用@ApiImplicitParams對其進行包裹

name:參數名稱?
value：參數的簡短描述?
required:是否必須傳遞的參數?
dataType:參數類型，可以為類名，也可以為基本類型（String，int，Boolean）?
paramType：參數的傳入（請求）類型，可選的值有path, query, body, header or form。（如果在路徑中提取參數用path比如:在／A／{XXX}路徑中得到XXX的值）

@ApiParam(name = “user”, value = “userValue”, required = true)?
對參數元信息的說明，一般這個注解只能被使用在JAX-RS 1.x/2.x的綜合環境下，和ApiImplicitParam注解類似

required:該參數是否必填?
value:該參數的簡短介紹

@ApiResponse(code = 200, message = “Successful — 請求已完成”)?
返回狀態碼的描述,如果有多個可以使用@ApiResponses注解進行包裹

code:服務器返回的狀態碼?
message：服務器返回狀態碼的簡短說明

sample：header中傳遞token

1 @ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

5,注意事項：

• 路徑參數比如一直傳遞 {id},需要在ApiImplicitParam注解中添加prameType=“path”
• 版本問題，需要刪除m2里面的jar包，2.2.2的swagger和1.5.6的spring-boot-prent才是絕配，試過很多最新的包，感覺多多少少都有點問題！
• 入參數和出參數都能用到一個實體類，注意檢查@ApiModel的value屬性

6參考文檔

可能還有其他沒有列出的參考文檔，見諒

https://gumutianqi1.gitbooks.io/specification-doc/content/tools-doc/spring-boot-swagger2-guide.html

http://www.jianshu.com/p/12f4394462d5

http://blog.didispace.com/springbootswagger2/

https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger

http://www.jianshu.com/p/b0b19368e4a8

?

文章轉自：https://blog.csdn.net/xxoo00xx00/article/details/77163399

轉載于:https://www.cnblogs.com/walblog/articles/9395125.html

總結

以上是生活随笔為你收集整理的swagger详解的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。