【Swagger】Springboot中集成Swagger2.0

一、前言

Swagger是一個強大的API文檔工具，使用Swagger可以輕鬆的將後端API的請求條件、所需參數、名稱等告知前端的開發人員，可以說是前後端進行溝通的橋樑；在本篇博客中就來介紹一下在Springboot中如何集成Swagger2.0，從而來幫助我們更好的進行開發工作。

二、使用前的準備

在Springboot中集成Swagger2.0，就需要準備Swagger2.0的相關依賴，在這裏以Maven項目管理工具來介紹相關的使用，首先我們想要到線上Maven倉庫中選取相關的依賴，所需要的依賴文件如下：

		<!--Swagger版本 2.9.2-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

三、正式進行開發工作

在項目中引入相關的依賴以後，我們就可以在項目中使用Swagger來對API進行註解說明了，首先我們來創建Swagger的一個配置類，如下所示：

@Configuration
@EnableSwagger2   // 啓動Swaggger2的註解
public class commonConfig {	

	@Value("${swagger.config.basePackage}")
	private String basePackage;
	
	@Value("${swagger.config.title}")
	private String title;	
	
	@Value("${swagger.config.description}")
	private String description;
		
	@Value("${swagger.config.version}")
	private String version;
	
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)	//指定API類型爲swagger2
				.apiInfo(apiInfo())						//用於定義API文檔的相關信息
				.select()//
				.apis(RequestHandlerSelectors.basePackage(basePackage)) //指定controller層包名
				.paths(PathSelectors.any())				//應用於所有的controller
				.build();
	}
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()//
				.title(title)				//API文檔的標題
				.description(description)	//關於這個文檔作用的描述
				.version(version)			//設置當前API文檔的版本號
				.build();
	}
}

由於我是在SpringBoot的配置文件（application.yml）中，進行了相關參數的配置，具體的配置如下：

swagger:
    config:
        basePackage: com.learn.controller
        title: Wechat Login API Document.
        description: Provide wechat login relasted interface.
        version: 1.0

完成了以上的工作以後，我們就可以在進行API開發的時候使用了，先來介紹controller層中的使用，直接上controller層的代碼：

@RestController
@Api(value = "WechatLoginController", tags = { "微信登錄服務API" })
public class WechatLoginController {
	@Autowired
	private WechatLoginService wechatLoginService;
	
	@Value("${web.backend.redirectUrl}")
	private String webCallbackUrl;
		
	@CrossOrigin
	@RequestMapping(value = "/wechat/login", method = RequestMethod.GET)
	@ApiOperation(value = "構建請求授權URL")
	@ApiImplicitParam(name = "redirect_url", value = "發起微信登錄的前端URL", required = true, paramType = "query", dataType = "String")
	public ResponseEntity<String> weChatLogin(@RequestParam("redirect_url") String redirect_url) {
		String takenUrl = wechatLoginService.createWechatAuthorizeUrl(redirect_url);
		return ResponseEntity.ok(takenUrl);
	}
}

接下來介紹Model層的使用，直接上代碼：

@Data
@ApiModel(value="WechatUser",description="微信用戶信息實體類")
public class WechatUser implements Serializable {

	private static final long serialVersionUID = 1L;
	@ApiModelProperty(value="id",required=true)
	private String id;
	@ApiModelProperty(value="微信用戶openId",required=true)
	private String openid; 
	@ApiModelProperty(value="微信用戶暱稱",required=true)
	private String nickname; 
	@ApiModelProperty(value="微信頭像地址",required=true)
	private String headimgurl;
	@ApiModelProperty(value="用戶性別1：男性|2：女性|0：未知",required=true)
	private String sex; 
	@Override
	public String toString() {
		return "openid=" + openid 
				+ "&nickname=" + nickname 
				+ "&headimgurl=" + headimgurl
				+ "&sex="+sex;
	}
}

經常要用到的註解如下：

@Api---用在類文件上，一般用於controller層
@ApiOperation---用於方法上，一般用於controller層中的API方法
@ApiImplicitParam---用於方法上，用於對API參數進行標註
@ApiImplicitParams---用於方法上，用於對API參數進行標註，適應於多個參數的情況，使用如下：
@ApiImplicitParams({
			@ApiImplicitParam(...),
			@ApiImplicitParam(...),
			@ApiImplicitParam(...) 
			})
@ApiModel---用於類上，一般用於model層
@ApiModelProperty---用於實體類中的屬性上

下面這一組關於註解的詳細說明，來源於網絡，參考博客：swagger2註解使用教程

@Api：用在請求的類上，表示對類的說明
    tags="說明該類的作用，可以在UI界面上看到的註解"
    value="該參數沒什麼意義，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、作用
    value="說明方法的用途、作用"
    notes="方法的備註說明"

@ApiImplicitParams：用在請求的方法上，表示一組參數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
        name：參數名
        value：參數的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪個地方
            · header --> 請求參數的獲取：@RequestHeader
            · query --> 請求參數的獲取：@RequestParam
            · path（用於restful接口）--> 請求參數的獲取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：參數類型，默認String，其它值dataType="Integer"       
        defaultValue：參數的默認值

@ApiResponses：用在請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
        code：數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類

@ApiModel：用於響應類上，表示一個返回響應數據的信息
            （這種一般用在post創建的時候，使用@RequestBody這樣的場景，
            請求參數無法使用@ApiImplicitParam註解進行描述的時候）
    @ApiModelProperty：用在屬性上，描述響應類的屬性

啓動項目，訪問對應的鏈接，如：http://xxxxx:port/swagger-ui.html，顯示如下界面：

四、注意

由上圖可以看出，我們雖然在model層的實體類上添加了相應的註解，但是並沒有顯示，出現這個問題的原因是因爲雖然在實體類上進行了註解，但是必須在controller層中使用@requestBody註解或者返回的數據類型中包含註解的實體類纔可以顯示，由於我寫的API中沒有滿足這樣的條件，所以沒有顯示