第九節:SpringBoot在線文檔Swagger2入門

Swagger2 是一個開源項目，用于為 RESTful Web 服務生成 REST API 文檔。它提供了一個用戶界面，可以通過 Web 瀏覽器訪問我們的 RESTful Web 服務,測試接口。

springboot集成Swagger2 3.0以下版本

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

package com.rumenz.lession9.controller.config; 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; /** * @className: Swagger2Config * @description: TODO 類描述 * @author: 入門小站 rumenz.com * @date: 2021/11/10 **/ @Configuration @EnableSwagger2 //Swagger2 3.0以下版本需要開啟的注解 public class Swagger2Config { @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo(){ Contact contact=new Contact("入門小站", "https://rumenz.com", "xenry@163.com"); return new ApiInfoBuilder() .title("入門小站接口文檔") .description("https://rumenz.com") .contact(contact).build(); } }

3.0以下開啟@EnableSwagger2這個注解

瀏覽器訪問http://127.0.0.1:8080/swagger-ui.html

Springboot集成Swagger2 3.0以版本

Swagger2 3.0版本使用更加簡單

io.springfox springfox-boot-starter 3.0.0

package com.rumenz.lession9.controller.config; 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; /** * @className: Swagger2Config * @description: TODO 類描述 * @author: 入門小站 rumenz.com * @date: 2021/11/10 **/ @Configuration public class Swagger2Config { @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo(){ Contact contact=new Contact("入門小站", "https://rumenz.com", "xenry@163.com"); return new ApiInfoBuilder() .title("入門小站接口文檔") .description("https://rumenz.com") .contact(contact).build(); } }

3.0以上版本不需要@EnableSwagger2這個注解

package com.rumenz; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.oas.annotations.EnableOpenApi; @SpringBootApplication @EnableOpenApi //Swagger2 3.0以上版本需要開啟的注解 public class Lession9Application { public static void main(String[] args) { SpringApplication.run(Lession9Application.class, args); } }

注意添加@EnableOpenApi注解

瀏覽器訪問http://127.0.0.1:8080/swagger-ui/

Swagger2常用注解

@Api用在類上,用于說明類功能的說明

@Api(tags = "入門小站Controller入口",value = "頁面上看不見的內容")

@ApiOperation(value = "方法的作用說明",notes = "方法的備注說明")

入參數說明

@ApiImplicitParams({@ApiImplicitParam(name = "page",value = "當前頁"),@ApiImplicitParam(name = "pageSize",value = "分頁大小")})

@ApiImplicitParam其它參數

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面 name：參數名 value：參數的漢字說明、解釋 required：參數是否必須傳 paramType：參數放在哪個地方 · header --> 請求參數的獲取：@RequestHeader · query --> 請求參數的獲取：@RequestParam · path（用于restful接口）--> 請求參數的獲取：@PathVariable · body（不常用） · form（不常用） dataType：參數類型，默認String，其它值dataType="Integer" defaultValue：參數的默認值

明請求返回的狀態碼及描述

@ApiResponses({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "參數錯誤")})

描述實體類

@ApiModel("用戶信息")

描述實體類的屬性

@ApiModelProperty(value = "名字",name = "name",example = "入門小站")

演示案例

RumenzController

package com.rumenz.lession9.controller; import io.swagger.annotations.*; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; import org.springframework.web.bind.annotation.*; /** * @className: RumenzController * @description: TODO 類描述 * @author: 入門小站 rumenz.com * @date: 2021/11/10 **/ @RestController @RequestMapping("/rumenz") //@Api用在類上,用于說明類功能的說明 @Api(tags = "入門小站Controller入口",value = "頁面上看不見的內容") public class RumenzController { @GetMapping("/index") public String index(){ return "入門小站"; } @GetMapping("/user") @ApiOperation(value = "方法的作用說明",notes = "方法的備注說明") //傳入參數說明 @ApiImplicitParams({@ApiImplicitParam(name = "page",value = "當前頁"),@ApiImplicitParam(name = "pageSize",value = "分頁大小")}) //說明請求返回的狀態碼及描述 @ApiResponses({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "參數錯誤")}) public String index1(@ApiParam("頁數") @RequestParam("page") Integer page,@ApiParam("每頁條數") Integer pageSize){ return "入門小站"; } @PostMapping("/save") @ApiOperation("保存用戶") public String save(@RequestBody User user){ return "入門小站"; } } @Data @NoArgsConstructor @AllArgsConstructor //描述實體類 @ApiModel("用戶信息") class User { //描述實體類的屬性 @ApiModelProperty(value = "名字",name = "name",example = "入門小站") private String name; @ApiModelProperty(value = "年齡",name="age",example = "20") private Integer age; @ApiModelProperty(value = "地址",name="address",example = "rumenz.com") private String address; @ApiModelProperty(value = "郵箱",name="email",example = "372669319@qq.com") private String email; }

在線測試接口可以點擊Try it out填入相關參數測試。

本小結源碼地址:

GitHub:https://github.com/mifunc/springboot/tree/main/lession8

Gitee:https://gitee.com/rumenz/springboot/tree/master/lession8

https://rumenz.com/rumenbiji/springboot-swagger20-rumen.html

介紹

我的博客 https://rumenz.com/ ,

我的工具箱 https://tooltt.com/

微信公眾號:【入門小站】

關注【入門小站】回復【1001】獲取 linux常用命令速查手冊

關注【入門小站】回復【1003】獲取 LeetCode題解【java語言實現】

關注【入門小站】回復【1004】獲取 Java基礎核心總結

關注【入門小站】回復【1009】獲取 阿里巴巴Java開發手冊

Spring Boot

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。