swagger快速開發

轉載：https://blog.csdn.net/xxoo00xx00/article/details/77163399

swagger 學習筆記

搭建環境:

• 1,jdk1.8
• 2,idea
• 3,spring-boot-starter-parent版本1.5.6.RELEASE
• 4，springfox-swagger2 And springfox-swagger-ui 版本2.2.2

1快速環境搭建

新建一個工程，file->new->Porject->Spring Initializr->next-以下圖所示（idea專業版本，社區版能夠到git上覆制pom文件）

pom.xml文件中添加以下內容(看清楚再複製，此處不是所有內容)

<properties> ... <swagger.version>2.2.2</swagger.version> ... </properties> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency>

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16

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

@EnableSwagger2 @Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com"))//掃描com路徑下的api文檔 .paths(PathSelectors.any())//路徑判斷 .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("《----我是title-----》")//標題 .description("《-----我是描述----》：http://www.google.com.hk")//描述 .termsOfServiceUrl("http://www.google.com.hk")//（不可見）條款地址 .contact(new Contact("zz","google.com.hk","123@qq.com"))//做者信息 .version("6.6.6")//版本號 .build(); } }

• 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

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

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

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15

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

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

• 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

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

2經常使用註釋描述

上半部 

下半部 

下下部 

3所有註釋列表

@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

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

• 1

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