技術(shù)分享 | Spring Boot 集成 Swagger

Swagger UI 允許任何人（無(wú)論您是開(kāi)發(fā)團(tuán)隊(duì)還是最終用戶(hù)）都可以可視化 API 資源并與之交互，而無(wú)需任何實(shí)現(xiàn)邏輯。它是根據(jù)您的 OpenAPI（以前稱(chēng)為 Swagger）規(guī)范自動(dòng)生成的，具有可視化文檔，可簡(jiǎn)化后端實(shí)現(xiàn)和客戶(hù)端使用。

為什么使用Swagger

跨語(yǔ)言性，支持 40 多種語(yǔ)言，Swagger 已經(jīng)慢慢演變成了 OpenAPI 規(guī)范；

Swagger UI 呈現(xiàn)出來(lái)的是一份可交互式的 API 文檔，我們可以直接在文檔頁(yè)面嘗試 API 的調(diào)用，省去了準(zhǔn)備復(fù)雜的調(diào)用參數(shù)的過(guò)程；

對(duì)于某些沒(méi)有前端界面 UI 的功能，可以用它來(lái)測(cè)試接口；

聯(lián)調(diào)方便，如果出問(wèn)題，直接測(cè)試接口，實(shí)時(shí)檢查參數(shù)和返回值,就可以快速定位問(wèn)題。

Swagger快速開(kāi)始

這里選擇 2.9.2 版本。

io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2

添加配置類(lèi)

添加一個(gè) Swagger 配置類(lèi)，在工程下新建 config 包并添加一個(gè) SwaggerConfig 配置類(lèi)。 SwaggerConfig.java ```java import com.google.common.collect.Lists; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.schema.ModelRef; 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 SwaggerConfig { //作為Springfox框架的主要接口的構(gòu)建器,提供合理的默認(rèn)值和方便的配置方法。 @Bean public Docket docket() { ParameterBuilder builder = new ParameterBuilder(); builder.parameterType("header").name("token") .description("token值") .required(true) .modelRef(new ModelRef("string")); // 在swagger里顯示header return new Docket(DocumentationType.SWAGGER_2) .groupName("aitest_interface") .apiInfo(apiInfo()) .globalOperationParameters(Lists.newArrayList(builder.build())) .select().paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("aitest-mini系統(tǒng)") .description("aitest-mini接口文檔") .contact(new Contact("tlibn", "", "103@qq.com")) .version("1.0") .build(); } }

添加控制器

添加一個(gè)控制器，在工程下新建 controller包并添加一個(gè)Controller控制器，如果已經(jīng)存在Controller控制器，則直接啟動(dòng)服務(wù)也可以，如上章我們編寫(xiě)了HogwartsTestUserController類(lèi)，此時(shí)直接啟動(dòng)服務(wù)即可。

打開(kāi) swagger 接口文檔界面

啟動(dòng) Spring Boot 服務(wù)，打開(kāi)瀏覽器，訪(fǎng)問(wèn)：http://127.0.0.1:8081/swagger-ui.html，進(jìn)入swagger接口文檔界面。?2

測(cè)試 展開(kāi) hogwarts-test-user-controller 的任意接口，輸入?yún)?shù)并點(diǎn)擊執(zhí)行，就可以看到接口測(cè)試結(jié)果了。  Swagger 常用注解 swagger 通過(guò)注解表明該接口會(huì)生成文檔，包括接口名、請(qǐng)求方法、參數(shù)、返回信息的等等。 Api：修飾整個(gè)類(lèi)，描述 Controller 的作用

Api(tags = “霍格沃茲測(cè)試學(xué)院-用戶(hù)管理模塊”, hidden = true)

ApiOperation：描述一個(gè)類(lèi)的一個(gè)方法，或者說(shuō)一個(gè)接口

ApiOperation(“查詢(xún)用戶(hù)列表”)

ApiParam：?jiǎn)蝹€(gè)參數(shù)描述 ApiModel：用對(duì)象來(lái)接收參數(shù)

ApiModel(value = “用戶(hù)登錄類(lèi)”, description = “請(qǐng)求類(lèi)”)

ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段

ApiModelProperty(value=“用戶(hù)id”, example=“1”,required=true)

ApiResponse：HTTP 響應(yīng)其中 1 個(gè)描述 ApiResponses：HTTP 響應(yīng)整體描述 ApiIgnore：使用該注解忽略這個(gè) API ApiError ：發(fā)生錯(cuò)誤返回的信息 ApiImplicitParam：一個(gè)請(qǐng)求參數(shù) ApiImplicitParams：多個(gè)請(qǐng)求參數(shù) 更多參見(jiàn) https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview 添加 Swagger 常用注解后的效果   添加 Swagger 常用注解后的示例代碼 HogwartsTestUserController.java

@Api(tags = “霍格沃茲測(cè)試學(xué)院-用戶(hù)管理模塊”, hidden = true)

@RestController

@RequestMapping("/api/user")

public class HogwartsTestUserController {

/** * 查詢(xún)用戶(hù)列表，返回一個(gè)JSON數(shù)組 * */ @ApiOperation("查詢(xún)用戶(hù)列表") @GetMapping("/users") @ResponseStatus(HttpStatus.OK) public Object getUsers(){ List list = getData(); return list; } /** * 查詢(xún)用戶(hù)信息，返回一個(gè)新建的JSON對(duì)象 * */ @ApiOperation("查詢(xún)用戶(hù)信息") @GetMapping("/users/{id}") @ResponseStatus(HttpStatus.OK) public Object getUser(@PathVariable("id") Long id){ if(Objects.isNull(id)){ return null; } List list= getData(); UserDto userDto = getUserDto(id, list); return userDto; } /** * 新增用戶(hù) * */ @ApiOperation("新增用戶(hù)") @PostMapping("/users") @ResponseStatus(HttpStatus.CREATED) public Object addUser(@RequestBody UserDto user){ List list= getData(); list.add(user);//模擬向列表中增加數(shù)據(jù) return user; } /** * 編輯用戶(hù) * */ @ApiOperation("編輯用戶(hù)") @PutMapping("/users/{id}") @ResponseStatus(HttpStatus.CREATED) public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){ List list = getData(); for (UserDto userDto:list) { if(id.equals(userDto.getId())){ userDto = user; break; } } return user; } /** * 刪除用戶(hù) * */ @ApiOperation("刪除用戶(hù)") @DeleteMapping("/users/{id}") @ResponseStatus(HttpStatus.NO_CONTENT) public Object deleteUser(@PathVariable("id") Long id){ List list = getData(); UserDto userDto = getUserDto(id, list); return userDto; } /** * 模擬數(shù)據(jù) * */ private List getData(){ List list=new ArrayList<>(); UserDto userDto = new UserDto(); userDto.setId(1L); userDto.setName("admin"); userDto.setPwd("admin"); list.add(userDto); userDto = new UserDto(); userDto.setId(2L); userDto.setName("HogwartsTest1"); userDto.setPwd("HogwartsTest1"); list.add(userDto); userDto = new UserDto(); userDto.setId(3L); userDto.setName("HogwartsTest2"); userDto.setPwd("HogwartsTest2"); list.add(userDto); userDto = new UserDto(); userDto.setId(4L); userDto.setName("HogwartsTest3"); userDto.setPwd("HogwartsTest3"); list.add(userDto); return list; } /** * 模擬根據(jù)id查詢(xún)列表中的數(shù)據(jù) * @param id * @param list * @return */ private UserDto getUserDto( Long id, List list) { UserDto UserDto = null; for (UserDto user : list) { if (id.equals(user.getId())) { UserDto = user; break; } } return UserDto; }

}

UserDto.java

@ApiModel(value = “用戶(hù)登錄類(lèi)”, description = “請(qǐng)求類(lèi)”)

public class UserDto {

@ApiModelProperty(value="用戶(hù)id", example="1",required=true) private Long id; @ApiModelProperty(value="用戶(hù)名稱(chēng)", example="hogwarts1",required=true) private String name; @ApiModelProperty(value="用戶(hù)密碼", example="hogwarts2",required=true) private String pwd; public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getPwd() { return pwd; } public void setPwd(String pwd) { this.pwd = pwd; }

}

請(qǐng)點(diǎn)擊更多技術(shù)文章，有驚喜喲

Spring Spring Boot

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶(hù)投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶(hù)投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。