Java EE 目錄:https://blog.csdn.net/dkbnull/article/details/87932809
Spring Boot 專欄:https://blog.csdn.net/dkbnull/category_9278145.html
Spring Cloud 專欄:https://blog.csdn.net/dkbnull/category_9287932.html
0. 開發環境
- IDE:IntelliJ IDEA 2017.1 x64
- jdk:1.8.0_91
- Spring Boot:2.1.1.RELEASE
1. 引入依賴
<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>
2. 建立Swagger2配置類
package cn.wbnull.springbootdemo.boot;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class GlobalSwagger2 {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//生成api文檔掃描路徑
.apis(RequestHandlerSelectors.basePackage("cn.wbnull.springbootdemo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//頁面标題
.title("SpringBootDemo Api")
//作者
.contact(new Contact("dukunbiao(null)", "https://github.com/dkbnull/SpringBootDemo", ""))
//版本号
.version("1.0")
//描述
.description("Base Java 1.8")
.build();
}
}
3. Restful接口增加注解
package cn.wbnull.springbootdemo.controller;
import com.alibaba.fastjson.JSONObject;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Scope;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Scope("prototype")
@Api(tags = "登入接口")
public class LoginController extends BaseController {
@PostMapping(value = "/login")
@ApiOperation("登入接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "sign", value = "簽名", required = true, dataType = "String"),
@ApiImplicitParam(name = "timestamp", value = "時間戳", required = true, dataType = "String"),
@ApiImplicitParam(name = "data", value = "請求資料", required = true, dataType = "String")
})
public JSONObject login(
@RequestParam(value = "sign") String sign,
@RequestParam(value = "timestamp") String timestamp,
@RequestParam(value = "data") String data
) throws Exception {
return baseService.login(data);
}
}
4. 測試
啟動程式
浏覽器通路 ip:port/context-path/swagger-ui.html 即可進入Api文檔頁面,部落客這裡位址為:http://localhost:8090/springbootdemo/swagger-ui.html
展開某個接口後可以看到具體求參數與傳回參數
點選 Try it out 按鈕可以進行測試,其中紅框輸入請求參數,輸入後點選Execute
可以看到傳回資訊
5. Swagger2常用注解
@Api():注解類,描述Controller的作用
tags = ”描述Controller的作用“
@ApiOperation():注解方法,描述具體接口的作用
value=“具體說明接口的作用”
notes="接口方法備注“
@ApiImplicitParams():注解接口方法,描述一組請求參數,可以包含多個@ApiImplicitParam()
@ApiImplicitParam():注解接口方法,描述一個具體的請求參數
name:請求參數名
value:請求參數描述
required:是否必傳
dataType:參數類型
defaultValue:預設值
@ApiResponses():注解接口方法,描述一組HTTP傳回值,可以包含多個@ApiResponse()
@ApiResponse():注解接口方法,描述一個HTTP響應資訊
code:HTTP傳回值
message:傳回資訊
response:抛出異常的類
@ApiModel():注解Model,描述響應資料Model類
@ApiModelProperty():注解屬性,描述響應Model類的屬性
@ApiIgnore():注解類,表示忽略這個Api
GitHub:https://github.com/dkbnull/SpringBootDemo
微信:https://mp.weixin.qq.com/s/hAg-sBKurC5QtcA5JFzjTQ
微網誌:https://weibo.com/ttarticle/p/show?id=2309404447241761849549
知乎:https://zhuanlan.zhihu.com/p/95993014