備忘錄六：Spring Boot + Swagger_UI

一：pom.xml 依賴

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.8.0</version>
		</dependency>

二：application.yaml 開關配置

# swagger
swagger: 
  switch: true

三：SwaggerConfig.java 配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	@Value("${swagger.switch}")
	private boolean swaggerSwitch;
	@Bean
	public Docket createRestApi() {
		Docket docket = new Docket(DocumentationType.SWAGGER_2);
		if (swaggerSwitch) {
			docket.enable(true);
		} else {
			docket.enable(false);
		}
		docket.apiInfo(apiInfo()).select()
				// 加了ApiOperation註解的類，才生成介面文件
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				// 包下的類，才生成介面文件
				.paths(PathSelectors.any()).build().securitySchemes(security());
		return docket;
	}
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("Demo").description("介面文件").termsOfServiceUrl("").version("0.1").build();
	}
	private List<ApiKey> security() {
		return newArrayList(new ApiKey("token", "token", "header"));
	}
}

四： 介面配置程式碼示例

/**
	  * @Title: list
	  * @Description: 測試
	  * @return void    返回型別
	  * @throws
	  */
	@ApiOperation(value="訊息列表查詢",notes="訊息列表查詢")
	@ApiImplicitParams({@ApiImplicitParam(name="userId",value="使用者ID",required=true,dataType="int")})
	@ApiResponses(value= {@ApiResponse(code = 200,message="Sucess",response=MsgPushInfoEntity.class,responseContainer="List")})
	@RequestMapping(value="/list",method=RequestMethod.POST)
	public List<MsgPushInfoEntity> list(@RequestBody MsgPushInfoEntity msg) {
		logger.info("===========" + msgPushInfoService.list().size() + "===========");
		logger.error("===========" + msgPushInfoService.list().size() + "===========");
		return  new ArrayList<MsgPushInfoEntity>();
	}

五：swagger-ui展示

六：Swagger註解說明

1.@Api

該註解將一個Controller（Class）標註為一個swagger資源（API）。在預設情況下，Swagger-Core只會掃描解析具有

@Api註解的類， 而會自動忽略其他類別資源（JAX-RS endpoints，Servlets等等）的註解。該註解包含以下幾個重要屬性：

  tags

  API分組標籤。具有相同標籤的API將會被歸併在一組內展示。

  value

  如果tags沒有定義，value將作為Api的tags使用

  description

  API的詳細描述，在1.5.X版本之後不再使用，但實際發現在2.0.0版本中仍然可以使用

2.@ApiOperation

在指定的（路由）路徑上，對一個操作或HTTP方法進行描述。具有相同路徑的不同操作會被歸組為同一個操作物件。

不同的HTTP請求方法及路徑組合構成一個唯一操作。此註解的屬性有：

  value

  對操作的簡單說明，長度為120個字母，60個漢字。

  notes

  對操作的詳細說明。

  httpMethod

  HTTP請求的動作名，可選值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。

  code

  預設為200，有效值必須符合標準的HTTP Status Code Definitions。

3.@ApiImplicitParams

  註解ApiImplicitParam的容器類，以陣列方式儲存。

@ApiImplicitParam

對API的單一引數進行註解。雖然註解@ApiParam同JAX-RS引數相繫結，但這個@ApiImplicitParam註解可以以統一的方式

定義引數列表，也是在Servelet及非JAX-RS環境下，唯一的方式引數定義方式。注意這個註解@ApiImplicitParam必須被

包含在註解@ApiImplicitParams之內。可以設定以下重要引數屬性：

  name

  引數名稱

  value

  引數的簡短描述

  required

  是否為必傳引數

  dataType

  引數型別，可以為類名，也可以為基本型別（String，int、boolean等）

  paramType

  引數的傳入（請求）型別，可選的值有path, query, body, header or form。

3.@ApiParam

  增加對引數的元資訊說明。這個註解只能被使用在JAX-RS 1.x/2.x的綜合環境下。其主要的屬性有：

  required

  是否為必傳引數

  value

  引數簡短說明

4.@ApiResponses

註解@ApiResponse的包裝類，陣列結構。即使需要使用一個@ApiResponse註解，也需要將@ApiResponse註解包含在

註解@ApiResponses內。

5.@ApiResponse

描述一個操作可能的返回結果。當REST API請求發生時，這個註解可用於描述所有可能的成功與錯誤碼。可以用，也可以不

用這個註解去描述操作的返回型別，但成功操作的返回型別必須在@ApiOperation中定義。如果API具有不同的返回型別，那麼需要分別定義返回值，並將返回型別進行關聯。但Swagger不支援同一返回碼，多種返回型別的註解。注意：這個註解必須被包含在@ApiResponses註解中。

  code

  HTTP請求返回碼。有效值必須符合標準的HTTP Status Code Definitions。

  message

  更加易於理解的文字訊息

  response

  返回型別資訊，必須使用完全限定類名，比如“com.xyz.cc.Person.class”。

  responseContainer

  如果返回型別為容器型別，可以設定相應的值。有效值為 "List", "Set" or "Map"，其他任何無效的值都會被忽略。

  Model的註解

  對於Model的註解，Swagger提供了兩個：@ApiModel及@ApiModelProperty，分別用以描述Model及Model內的屬性。

6.@ApiModel

提供對Swagger model額外資訊的描述。在標註@ApiOperation註解的操作內，所有的類將自動被內省（introspected），

但利用這個註解可以做一些更加詳細的model結構說明。主要屬性有：

  value

  model的別名，預設為類名

  description

  model的詳細描述

7.@ApiModelProperty

  對model屬性的註解，主要的屬性值有：

  value

  屬性簡短描述

  example

  屬性的示例值

  required

  是否為必須值

七：關於TOKER問題

考慮到安全的問題，每次請求API需要對使用者進行驗證與授權。目前主流的驗證方式採用請求頭部（request header）傳遞token，即使用者登入之後獲取一個token，然後每次都使用這個token去請求API。如果想利用swagger-UI進行API測試，必須顯式為每個需要驗證的API指定token引數。