Spring Boot+Swagger_UI怎么配置

本篇內容主要講解“Spring Boot+Swagger_UI怎么配置”，感興趣的朋友不妨來看看。本文介紹的方法操作簡單快捷，實用性強。下面就讓小編來帶大家學習“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版本之后不再使用，但實際發(fā)現在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注解可以以統(tǒng)一的方式

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

包含在注解@ApiImplicitParams之內?？梢栽O置以下重要參數屬性：

  name

  參數名稱

  value

  參數的簡短描述

  required

  是否為必傳參數

  dataType

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

  paramType

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

3.@ApiParam

  增加對參數的元信息說明。這個注解只能被使用在JAX-RS 1.x/2.x的綜合環(huán)境下。其主要的屬性有：

  required

  是否為必傳參數

  value

  參數簡短說明

4.@ApiResponses

注解@ApiResponse的包裝類，數組結構。即使需要使用一個@ApiResponse注解，也需要將@ApiResponse注解包含在

注解@ApiResponses內。

5.@ApiResponse

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

用這個注解去描述操作的返回類型，但成功操作的返回類型必須在@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注解的操作內，所有的類將自動被內?。╥ntrospected），

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

  value

  model的別名，默認為類名

  description

  model的詳細描述

7.@ApiModelProperty

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

  value

  屬性簡短描述

  example

  屬性的示例值

  required

  是否為必須值

七：關于TOKER問題

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

到此，相信大家對“Spring Boot+Swagger_UI怎么配置”有了更深的了解，不妨來實際操作一番吧！這里是億速云網站，更多相關內容可以進入相關頻道進行查詢，關注我們，繼續(xù)學習！