Swagger使用教程——快速上手swagger
一、swagger簡介
官網(wǎng)：https://swagger.io/
1、認(rèn)識swagger
swagger是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RestFul風(fēng)格的web服務(wù)，總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器斷的代碼，允許API來始終保持同步。
作用：
1. 接口的文檔在線自動(dòng)生成。
2. 功能測試。
2、Swagger是一組開源項(xiàng)目，其中主要要項(xiàng)目如下：
-
Swagger-tools:提供各種與Swagger進(jìn)行集成和交互的工具。例如模式檢驗(yàn)、Swagger 1.2文檔轉(zhuǎn)換成Swagger 2.0文檔等功能。
-
Swagger-core: 用于Java/Scala的的Swagger實(shí)現(xiàn)。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進(jìn)行集成。
-
Swagger-js: 用于JavaScript的Swagger實(shí)現(xiàn)。
-
Swagger-node-express: Swagger模塊，用于node.js的Express web應(yīng)用框架。
-
Swagger-ui：一個(gè)無依賴的HTML、JS和CSS集合，可以為Swagger兼容API動(dòng)態(tài)生成優(yōu)雅文檔。
-
Swagger-codegen：一個(gè)模板驅(qū)動(dòng)引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。
二、SpringBoot集成Swagger
1、新建SpringBoot項(xiàng)目，導(dǎo)入swagger依賴
<!--swagger依賴-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、編寫swagger的配置文件
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 創(chuàng)建API應(yīng)用
* apiInfo() 增加API相關(guān)信息
* 通過select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來控制哪些接口暴露給Swagger來展現(xiàn)，
* 指定掃描的包路徑來定義指定要建立API的目錄。
* @return
*/
@Bean
public Docket coreApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(adminApiInfo())
.groupName("adminApi")
.select()
//只顯示admin下面的路徑
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("尚融寶后臺(tái)管理系統(tǒng)--api文檔")
.description("尚融寶后臺(tái)管理系統(tǒng)接口描述")
.version("1.0")
.contact(new Contact("李燕茹","http://baidu.com","728831102@qq.com"))
.build();
}
}
3、添加文檔內(nèi)容
在完成了上述配置后，其實(shí)已經(jīng)可以生產(chǎn)文檔內(nèi)容，但是這樣的文檔主要針對請求本身，描述的主要來源是函數(shù)的命名，通常需要自己增加一些說明來豐富文檔內(nèi)容。
Swagger使用的注解及其說明：
@Api：用在類上，說明該類的作用。
@ApiOperation：注解來給API增加方法說明。
@ApiParam：定義在參數(shù)上
@ApiResponses：用于表示一組響應(yīng)
@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
l code：數(shù)字，例如400
l message：信息，例如"請求參數(shù)沒填好"
l response：拋出異常的類
@ApiModel：描述一個(gè)Model的信息（一般用在請求參數(shù)無法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）
l @ApiModelProperty：描述一個(gè)model的屬性
@ApiImplicitParams: 用在方法上包含一組參數(shù)說明。
@ApiImplicitParam：用來注解來給方法入?yún)⒃黾诱f明。
@ApiImplicitParam的參數(shù)說明：
| paramType：指定參數(shù)放在哪個(gè)地方 | header：請求參數(shù)放置于Request Header，使用@RequestHeader獲取 query：請求參數(shù)放置于請求地址，使用@RequestParam獲取 path：（用于restful接口）–>請求參數(shù)的獲?。篅PathVariable body：（不常用） form（不常用） |
|---|---|
| name：參數(shù)名 | |
| dataType：參數(shù)類型 | |
| required：參數(shù)是否必須傳 | true | false |
| value：說明參數(shù)的意思 | |
| defaultValue：參數(shù)的默認(rèn)值 |
案例：
//實(shí)體類
//entity的實(shí)體類中可以添加一些自定義設(shè)置
@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value="IntegralGrade對象", description="積分等級表")
public class IntegralGrade implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "編號")
@TableId(value = "id", type = IdType.AUTO)
private Long id;
@ApiModelProperty(value = "積分區(qū)間開始")
private Integer integralStart;
@ApiModelProperty(value = "積分區(qū)間結(jié)束")
private Integer integralEnd;
@ApiModelProperty(value = "借款額度")
private BigDecimal borrowAmount;
@ApiModelProperty(value = "創(chuàng)建時(shí)間")
private LocalDateTime createTime;
@ApiModelProperty(value = "更新時(shí)間")
private LocalDateTime updateTime;
@ApiModelProperty(value = "邏輯刪除(1:已刪除，0:未刪除)")
@TableField("is_deleted")
@TableLogic
private Boolean deleted;
}
//controler層
@RestController
@RequestMapping("/admin/integralGrade")
@Api(value = "積分等級管理")
public class IntegralGradeController {
@Resource
private IntegralGradeService integralGradeService;
@GetMapping("/list")
@ApiOperation("積分等級列表")
public Result listAll(){
List<IntegralGrade> list = integralGradeService.list();
return Result.ok().data("list",list);
}
@DeleteMapping("/remove/{id}")
@ApiOperation(value = "根據(jù)id刪除積分等級",notes = "邏輯刪除")
public Result removeById(
@ApiParam(value = "數(shù)據(jù)id",required = true,example = "1")
@PathVariable Long id){
boolean result = integralGradeService.removeById(id);
if (result){
return Result.ok().message("刪除成功");
}else {
return Result.error().message("刪除失敗");
}
}
@PostMapping("/save")
@ApiOperation(value = "新增積分等級")
public Result save(@ApiParam(value = "積分等級對象",required = true) @RequestBody IntegralGrade integralGrade){
boolean result = integralGradeService.save(integralGrade);
if (result){
return Result.ok().message("新增成功");
}else {
return Result.error().message("新增失敗");
}
}
@PutMapping("/updateById")
@ApiOperation(value = "根據(jù)id修改積分等級")
public Result updateById(@ApiParam(value = "積分等級對象",required = true) @RequestBody IntegralGrade integralGrade){
boolean result = integralGradeService.updateById(integralGrade);
if (result){
return Result.ok().message("修改成功");
}else {
return Result.error().message("修改失敗");
}
}
@GetMapping("/getById/{id}")
@ApiOperation(value = "根據(jù)id查詢積分等級")
public Result getById(@ApiParam(value = "數(shù)據(jù)id",required = true,example = "1") @PathVariable Long id){
IntegralGrade result = integralGradeService.getById(id);
if (result == null){
return Result.error().message("查詢失敗");
}else {
return Result.ok().data("integralGrade",result);
}
}
}
4、訪問
完成上述代碼，啟動(dòng)Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html
5、進(jìn)行功能測試
點(diǎn)擊try it out 可以測試接口
有一個(gè)需要注意的地方：
Conntroller中定義的方法必須在@RequestMapper中顯示的指定RequestMethod類型，否則SawggerUi會(huì)默認(rèn)為全類型皆可訪問， API列表中會(huì)生成7條項(xiàng)目。
6、參考
http://blog.didispace.com/springbootswagger2/
Swagger官網(wǎng) ：http://swagger.io/
Spring Boot & Swagger UI ： http://fruzenshtein.com/spring-boot-swagger-ui/文章來源：http://www.zghlxwxcb.cn/news/detail-422586.html
Github：https://github.com/swagger-api/swagger-core/wiki/Annotations文章來源地址http://www.zghlxwxcb.cn/news/detail-422586.html
到了這里，關(guān)于swagger使用教程——快速使用swagger的文章就介紹完了。如果您還想了解更多內(nèi)容，請?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
