swagger簡介
Swagger?的目標是為REST APIs 定義一個標準的，與語言無關(guān)的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網(wǎng)絡流量檢測的情況下能發(fā)現(xiàn)和理解各種服務的功能膏斤。當服務通過Swagger定義彻舰，消費者就能與遠程的服務互動通過少量的實現(xiàn)邏輯。類似于低級編程接口诫咱，Swagger去掉了調(diào)用服務時的很多猜測笙隙。
瀏覽 Swagger-Spec 去了解更多關(guān)于Swagger 項目的信息，包括附加的支持其他語言的庫坎缭。
pom.xml(添加依賴)
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
swagger配置文件
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@Configuration
@EnableWebMvc
//需要掃描的接口包
public class Swagger2Config {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
// 一些接口文檔信息的簡介
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs")
.description("spring Boot 中構(gòu)建RESTful API")
.termsOfServiceUrl("")
.contact("caizi")
.version("1.0")
.build();
}
}
swagger 注解用法
1.對整個controller的描述注解
@Api(value = "信息", description = "管理信息的API")
2.對每一個接口的描述
@ApiOperation(value = "修改信息", notes = "信息對象竟痰，信息標簽，信息id")
3.對每個參數(shù)進行描述
@ApiParam(required = true, name = "postData"掏呼，value = "用戶信息json數(shù)據(jù)") @RequestParam("tagData") String tagData
示例(在線測試時坏快，需要注意參數(shù)的paramType參數(shù)的類型)
@Api(value = "CorpusController", description = "管理語料的方法")
public class CorpusController {
@Autowired
ICorpusService iCorpusService;
@GETMapping(value = "/getCorpusByUserName")
@ApiOperation(value = "getCorpusByUserName", notes = "獲取語料")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用戶賬號", required = true, dataType = "STRING",, paramType = "query"),
@ApiImplicitParam(name = "corpusType", value = "語料分組類型", required = true, dataType = "STRING",, paramType = "query")
})
public String getCorpusByUserName(@RequestParam("userName") String userName,
@RequestParam("corpusType") String corpusType) {
String result = iCorpusService.getCorpusByUserName(userName, corpusType).toString();
return result;
}
}
使用
// 如果發(fā)布服務器可能路徑還需要加上項目名
http://ip:port/swagger-ui.html
swagger成功訪問頁面
結(jié)語
當然這些公共的配置，都可以配置成spring-boot-starter這樣方便后面的調(diào)用憎夷，同時也能更好的維護莽鸿。
// swagger-spring-boot-starter 源碼下載地址
github: https://github.com/zg091418/swagger2springbootstarter
