springboot 整合swagger2
相信很多人都用過postman，使用postman其實可以很簡便的進行介面除錯，但是呢，每次還要寫url，以及要新增引數名字(很容易寫錯)。所以啊，swagger2優勢就體現出來了，它只需要新增少量註解即可在專案下除錯介面，並且可以根據專案是否是測試還是生產環境，可以顯示或禁止頁面介面除錯，介紹就到這裡，開始寫整合部分。
一.maven新增依賴
此處使用的是2.7.0版本，下面的ui二選一即可，springfox-swagger-ui是官方提供的UI介面（本人一直使用的是這個），swagger-bootstrap-ui是基於左右選單風格，GitHub專案地址:https://github.com/xiaoymin/Swagger-Bootstrap-UI
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <!--springfox-swagger-ui http://localhost:8010/swagger-ui.html--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency> <!--bootstap-ui http://localhost:8010/doc.html--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.6</version> </dependency>
二.swagger2配置檔案
本人喜歡將swagger2一些引數寫到配置檔案中，方便以後修改，也可以將其寫死。在application.yml中新增以下配置。enable為true是表示在swagger-ui.html中顯示介面。
swagger:
enable: true
info:
version: 0.1
title: 兮川專案的介面
description: 薛定諤的貓，你不去驗證，就無法知道真假
user_name: 兮川
url:
email:在config配置中，apiInfos()方法是新增通用屬性的，如郵箱、版本、描述等。headerInfos()方法是新增頭引數，如果每個介面頭中沒有通用引數的話，可以將其刪除，順便將每一個介面掃描中將.globalOperationParameters(headerInfos())也刪除掉。
每一個介面掃描中,.apiInfo(apiInfo())表示新增通用屬性。.enable(enableSwagger)表示是否在頁面顯示此介面列表。.groupName("訪客介面列表")表示介面列表的名字(名字必須唯一)。.apis(RequestHandlerSelectors.basePackage("com.xichuan.visit.controller"))表示掃描一個package下的所有介面。.globalOperationParameters(headerInfos())表示新增頭資訊。
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Value("${swagger.enable}")
private boolean enableSwagger;
@Value("${swagger.info.version}")
private String version;
@Value("${swagger.info.title}")
private String title;
@Value("${swagger.info.description}")
private String description;
@Value("${swagger.info.user_name}")
private String userName;
@Value("${swagger.info.url}")
private String url;
@Value("${swagger.info.email}")
private String email;
/**訪客介面*/
@Bean
public Docket visitApis() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enableSwagger)
.groupName("訪客介面列表")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xichuan.visit.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(headerInfos());
}
/**通用介面*/
@Bean
public Docket generalApis() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enableSwagger)
.groupName("通用介面列表")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xichuan.general.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(headerInfos());
}
private List<Parameter> headerInfos(){
//新增head引數
List<Parameter> headerParams = new ArrayList<>();
ParameterBuilder schoolIdParams = new ParameterBuilder();
schoolIdParams.name("school_id").description("school_id").modelRef(new ModelRef("String")).parameterType("header").defaultValue("").required(false).build();
ParameterBuilder devMacParams = new ParameterBuilder();
devMacParams.name("dev_mac").description("dev_mac").modelRef(new ModelRef("String")).parameterType("header").defaultValue("00:08:22:B6:10:04").required(false).build();
headerParams.add(schoolIdParams.build());
headerParams.add(devMacParams.build());
return headerParams;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.contact(new Contact(userName,url,email))
.version(version)
.build();
}
}
三.在程式碼中運用
在程式碼中運用其實很簡單，主要使用@Api、@ApiOperation、@ApiIgnore三個註解就可以完成平時開發工作。先上一下程式碼塊。
@RestController
@RequestMapping("/xichuan/RSA")
@Api(tags = "資料RSA AES加密傳輸")
public class RSAController {
@Autowired
RSAService rsaService;
@GetMapping("/key")
@ApiOperation("通過平臺code獲取公鑰")
@ApiImplicitParam(name = "platform_code",value = "平臺Code",defaultValue ="message_send" ,required = true,dataType = "String",paramType = "query")
public Response getPublicKeyByCode(@RequestParam("platform_code")String platformCode){
return rsaService.getPublicKeyByCode(platformCode);
}
@PostMapping("/message")
@ApiOperation("通過AES加密的code pwd,RSA加密的key,獲取使用者詳細AES加密資訊")
public Response getUserMessageDetail(@RequestBody Message message)throws Exception{
return rsaService.getUserMessageDetail(message);
}
}public class Message {
@ApiModelProperty(example = "message_send")
@JsonProperty("platform_code")
public String platformCode;
@ApiModelProperty(example = "123www")
@JsonProperty("encrypt_key")
public String encryptKey;
@ApiModelProperty(example = "456ccd")
public String data;
public Message(){}
public Message(String platformCode,String encryptKey,String data){
this.platformCode = platformCode;
this.encryptKey = encryptKey;
this.data = data;
}
}相信看完例項，你會大致理解這些註解的作用了。
@Api(tags = " ")放在controller類上面，表示此類介面列表的名字；
@ApiOperation(value=" "，note=" ")，寫在方法上，表示此方法的作用，其中value表示此方法的名字，note可以寫自己對此方法的理解以及描述等
@ApiImplicitParam(name = "",value = "",defaultValue ="" ,required = true,dataType = "",paramType = "")，此註解寫在方法上，（本人不怎麼使用）。name表示引數名字。value表示引數名稱。defaultValue表示預設值。requared表示此引數是否必須有值。dataType表示引數的型別。paramType 表示引數的型別，header-->請求引數的獲取在@RequestHeader中；query-->請求引數的獲取在@RequestParam中；path（用於restful介面）-->請求引數的獲取在@PathVariable中；body（不常用）；form（不常用）
@ApiImplicitParams放在方法上，指的是一組引數的說明
@ApiIgnore：寫方法上，表示此介面在swagger不顯示，寫在類上，表示此類中的介面在swagger全部不顯示。
在@RequestBody引數中，如果想指定每個欄位的預設值，需要使用@ApiModelProperty註解。@JsonProperty("encrypt_key")是為了在呼叫時，將其呼叫的引數格式寫為下劃線格式。
新增完這些配置中，執行你的專案，然後訪問http://localhost:8080/swagger-ui.html(此處只是個例子，注意埠號要與你的專案一致)即可使用swagger2來呼叫你的介面了。
