系列文章目錄
第一章 SpringBoot系列之從0搭建項目第二章 SpringBoot系列返回json數據
第三章 SpringBoot系列GlobalException全局異常捕獲
第四章 SpringBoot系列整合Mybatis做增刪改查
第五章 SpringBoot系列配置JPA訪問數據
第六章 SpringBoot系列使用JdbcTemplate操作數據
第七章 SpringBoot系列靜態資源處理，訪問磁盤文件
第八章 SpringBoot系列實現任務調度Scheduled
文章目錄
前言
日常開發過程中接口文檔是必不可少得一項工作，由於接口增加、變更使得文檔變得難以維護，也容易忘記或漏掉接口，說實話大部分開發者也不太願意去維護這么個文檔，還有就是接口測試角度分析，通常我們開發完一個接口需要使用接口調用工具postman等等http調用工具來做接口的測試，swagger的出現簡直就是我們開發者的福音，swagger可自動為我們生成接口文檔頁面，可在頁面直接查看接口入參、出參以及做接口測試，話不多說接下來我們就來看看SpringBoot項目是如何接入swagger api文檔神器的。
提示：以下是本篇文章正文內容，下面案例可供參考
一、swagger3注解使用介紹
@Api 寫在controller類上，入參API接口名稱/介紹
@ApiOperation 用在接口方法上，入參接口名稱/介紹
@ApiModel 用在數據實體類上，入參實體類名稱/介紹
@ApiModelProperty 用在對象數據實體屬性上，入參屬性名稱/介紹
@ApiParam 單個請求參數說明
@ApiImplicitParams 接口參數說明
@ApiResponses 接口響應提示(比如400參數不對等等注釋)
@ApiIgnore 忽略接口方法
二、代碼整合demo
1.pom.xml引入依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.接口代碼中加入swagger注解
①controller類
package com.example.demo.controller;
import com.example.demo.dao.JdbcPersonDao;
import com.example.demo.dto.JsonDataDTO;
import com.example.demo.model.PersonDO;
import com.example.demo.service.PersonService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@Api("swagger3演示controller")
@RestController
@RequestMapping("/")
public class DemoController {
@Autowired
private PersonService personService;
@Autowired
private JdbcPersonDao jdbcPersonDao;
@ApiOperation("test接口")
@PostMapping("/test")
public String test(@RequestBody PersonDO personDO) {
return "實體類入參demo";
}
@ApiOperation("test接口")
@GetMapping("/test")
public String test() {
return "Hello World";
}
@ApiOperation("getJsonData接口")
@GetMapping("/getJsonData")
public JsonDataDTO getJsonData() {
JsonDataDTO jsonDataDTO = new JsonDataDTO();
jsonDataDTO.setName("張三");
jsonDataDTO.setAge(18);
jsonDataDTO.setSex("男");
return jsonDataDTO;
}
@ApiOperation("globalExceptionTest接口")
@GetMapping("/globalExceptionTest")
public void globalExceptionTest() throws Exception {
throw new Exception("發生異常啦！！！");
}
@ApiOperation("selectPersonInfo接口")
@GetMapping("/selectPersonInfo")
public PersonDO selectPersonInfo(@RequestParam("id") @ApiParam("主鍵ID") Long id) {
return personService.selectPersonInfo(id);
}
@ApiOperation("selectPersonInfoJpaDemo接口")
@GetMapping("/selectPersonInfoJpaDemo")
public PersonDO selectPersonInfoJApademo(@RequestParam("id") @ApiParam("主鍵ID") Long id) {
return jdbcPersonDao.getPersonDO(id);
}
@ApiOperation("queryDataForJdbc接口")
@GetMapping("/queryDataForJdbc")
public PersonDO queryDataForJdbc(@RequestParam("id") @ApiParam("主鍵ID") Long id) {
return personService.selectPersonInfoJpaDemo(id);
}
}
②接口參數對象DTO
package com.example.demo.dto;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel("swagger接口對象實體類")
@Data
public class JsonDataDTO {
/** * 姓名 */
@ApiModelProperty("姓名")
private String name;
/** * 年齡 */
@ApiModelProperty("年齡")
private Integer age;
/** * 性別 */
@ApiModelProperty("性別")
private String sex;
}
3.增加swagger配置類
package com.example.demo.config;
import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.HashSet;
@EnableOpenApi
@Configuration
public class SwaggerConfiguration {
@Value("server.port")
private String port;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).pathMapping("/")
// 定義是否開啟swagger，false為關閉，可以通過變量控制
.enable(true)
// 將api的元信息設置為包含在json ResourceListing響應中。
.apiInfo(apiInfo())
// 接口調試地址
.host("http://localhost:"+port)
// 選擇哪些接口作為swagger的doc發布
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
// 支持的通訊協議集合
.protocols(getProtocols("https", "http"));
}
private HashSet<String> getProtocols(String https, String http) {
HashSet set = new HashSet<String>();
set.add(https);
set.add(http);
return set;
}
/** * API 頁面上半部分展示信息 */
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("Demo Api Doc")
.description("rest接口文檔 lc")
.version("v1.0")
.build();
}
}
4.設置排除攔截路徑
比如項目中登錄攔截器，安全框架攔截等等，需要排除swagger路徑不然可能會被攔截導致訪問不了swagger界面。
/swagger**/** /webjars/** /v3/** /doc.html 二、API可視化界面效果
POST請求接口，點右上角Try it out 可編輯入參並Execute做接口測試，往下就是響應信息，從圖片我們可以看到代碼中注釋說明/名稱。
GET請求接口，點右上角Try it out 可編輯入參並Execute做接口測試，往下就是響應信息，從圖片我們可以看到代碼中注釋說明/名稱。
總結
有到了總結時刻了，一句話：簡直太好用啦！快點把它引入到你們項目當中，減少工作量！！！