→ springboot 集成 Swagger2 ←
1. 案例
這次直接使用 2.5.6 的 spring-boot 。
-
依賴：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.6</version> <relativePath/> <!-- lookup parent from repository --> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--swagger3--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies> -
啟動(dòng)類加注解
@EnableOpenApi -
新建測(cè)試類
@RestController @RequestMapping("/test") public class SwaggerController { @GetMapping("/get") public String getStr(String str) { return "SELECT " + str; } @PostMapping("/post") public String postStr(String str) { return "CREATE " + str; } @PutMapping("/put") public String putStr(String str) { return "UPDATE " + str; } @NoSwagger @PatchMapping("/patch") public String patchStr(String str) { return "UPDATE " + str; } @DeleteMapping("/delete") public String deleteStr(String str) { return "DELETE " + str; } } -
訪問 http://127.0.0.1:8080/swagger-ui.html ，沒錯(cuò)，又是 Error 頁面
此部分參考：https://blog.csdn.net/mmmm0584/article/details/117786055
在swagger3.0中，swagger-ui.html的位置發(fā)生了變化：
??→??
所以路徑也變了：http://127.0.0.1:8080/swagger-ui.html → http://127.0.0.1:8080/swagger-ui/index.html
- 訪問 http://127.0.0.1:8080/swagger-ui/index.html
2. info 配置
新建一個(gè)配置類：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.HashSet;
@Configuration
public class Swagger3Conf {
@Bean
public Docket createDocket() {
return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本號(hào)
.apiInfo(createApiInfo());
}
@Bean
public ApiInfo createApiInfo() {
// // 寫法一
// return new ApiInfoBuilder()
// .title("Swagger3 文檔案例")
// .description("Swagger ：一套圍繞 Open API 規(guī)范構(gòu)建的一款 RESTful 接口的文檔在線自動(dòng)生成和功能測(cè)試 API 。")
// .version("1.0.1")
// .contact(
// // name url email
// new Contact("364.99°的文檔", // 文檔發(fā)布者名稱
// "https://blog.csdn.net/m0_54355172", // 文檔發(fā)布者的網(wǎng)站地址
// "2190826197@qq.com" // 文檔發(fā)布者的郵箱
// )
// )
// .build();
// 寫法二
return new ApiInfo(
"Swagger3 文檔案例",
"Swagger ：一套圍繞 Open API 規(guī)范構(gòu)建的一款 RESTful 接口的文檔在線自動(dòng)生成和功能測(cè)試 API 。",
"1.0.1",
"https://blog.csdn.net/m0_54355172",
new Contact("364.99°的文檔", // 文檔發(fā)布者名稱
"https://blog.csdn.net/m0_54355172", // 文檔發(fā)布者的網(wǎng)站地址
"2190826197@qq.com" // 文檔發(fā)布者的郵箱
),
"364.99°",
"https://blog.csdn.net/m0_54355172",
new HashSet<>());
}
}
-
DocketSwagger 的實(shí)例，可通過 Docket 對(duì)象來配置 Swagger； -
ApiInfo文件描述的配置對(duì)象。
3. Docket 配置
1. 開關(guān)配置
@Bean
public Docket createDocket() {
return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本號(hào)
.enable(false)// 關(guān)閉文檔
.apiInfo(createApiInfo());
}
注意： 一般只有在測(cè)試環(huán)境才會(huì)用到 Swagger，在生產(chǎn)環(huán)境中會(huì)把它關(guān)閉掉，為了安全與效率。
2. 掃描路徑
.select()
.apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
.build()
3. 路徑匹配
新建一個(gè)控制器：
@Api(tags = "other 接口 API")
@RestController
@RequestMapping("/other")
public class OtherController {
@GetMapping("getInfo")
public String getInfo() {
return "information";
}
}
.select()
.paths(PathSelectors.ant("/other/**"))
.build()
4. 分組管理
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 java.util.HashSet;
@Configuration
public class Swagger3Conf {
@Bean
public Docket createDocket01() {
return new Docket(DocumentationType.OAS_30)// 指定 Swagger3 版本號(hào)
.groupName("other 組")
.enable(true)// 關(guān)閉文檔
.select()
.paths(PathSelectors.ant("/other/**"))
.build()
.apiInfo(createApiInfo());
}
@Bean
public Docket createDocket02() {
return new Docket(DocumentationType.OAS_30)
.groupName("test 組")
.select()
.apis(RequestHandlerSelectors.basePackage("com.chenjy.swagger2.controller"))
.build()
.apiInfo(
new ApiInfoBuilder()
.title("Swagger3 文檔案例")
.build()
);
}
@Bean
public ApiInfo createApiInfo() {
// // 寫法一
// return new ApiInfoBuilder()
// .title("Swagger3 文檔案例")
// .description("Swagger ：一套圍繞 Open API 規(guī)范構(gòu)建的一款 RESTful 接口的文檔在線自動(dòng)生成和功能測(cè)試 API 。")
// .version("1.0.1")
// .contact(
// // name url email
// new Contact("364.99°的文檔", // 文檔發(fā)布者名稱
// "https://blog.csdn.net/m0_54355172", // 文檔發(fā)布者的網(wǎng)站地址
// "2190826197@qq.com" // 文檔發(fā)布者的郵箱
// )
// )
// .build();
// 寫法二
return new ApiInfo(
"Swagger3 文檔案例",
"Swagger ：一套圍繞 Open API 規(guī)范構(gòu)建的一款 RESTful 接口的文檔在線自動(dòng)生成和功能測(cè)試 API 。",
"1.0.1",
"https://blog.csdn.net/m0_54355172",
new Contact("364.99°的文檔", // 文檔發(fā)布者名稱
"https://blog.csdn.net/m0_54355172", // 文檔發(fā)布者的網(wǎng)站地址
"2190826197@qq.com" // 文檔發(fā)布者的郵箱
),
"364.99°",
"https://blog.csdn.net/m0_54355172",
new HashSet<>());
}
}
文章來源：http://www.zghlxwxcb.cn/news/detail-770160.html
4. 常用注解
1. 說明
和 Swagger2 一樣，其常用注解還是如下幾個(gè)：文章來源地址http://www.zghlxwxcb.cn/news/detail-770160.html
| 常用注解 | 注解說明 | 常用屬性 | 屬性說明 |
|---|---|---|---|
@Api |
類注解，常用來給文檔中的控制器取別名 | tags | 別名 |
@ApiOperation |
方法/類注解，常用來描述方法 | value notes |
方法說明 方法備注 |
@ApiParam |
參數(shù)/方法/屬性注解，常用來描述參數(shù) | name value required |
參數(shù)名 補(bǔ)充描述 是否必須 |
@ApiIgnore |
方法/屬性注解，使被標(biāo)注方法不生成文檔 | - | - |
@ApiImplicitParam |
方法注解，描述一個(gè)參數(shù) | name value name required paramType dataType defaultValue |
參數(shù)名 補(bǔ)充說明 是否必傳 參數(shù)位置（header、query、path） 參數(shù)類型（默認(rèn) String） 默認(rèn)值 |
@ApiImplicitParams |
搭配 @ApiImplicitParam 一起使用，描述一組參數(shù) |  |
|
@ApiResponse |
方法注解，表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息 | code message response |
整型 字符串 異常信息（默認(rèn) String 類型） |
@ApiResponses |
搭配 @ApiResponse 一起使用，參考 @ApiImplicitParams | ||
@ApiModel |
類注解，當(dāng)此實(shí)體類被作為返回類型用于 API 幫助文檔中的接口方法中，此注解被解析 | value description |
實(shí)體類名 補(bǔ)充描述 |
@ApiModelProperty |
屬性注解，搭配 @ApiModel 使用 | value example hidden |
屬性名 示例 是否隱藏 |
2. 案例
import com.chenjy.swagger2.dto.TestDto;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
@Api(tags = {"test 接口 API"})
@RestController
public class SwaggerController {
@ApiResponses({
@ApiResponse(code = 1, message = "查詢成功"),
@ApiResponse(code = -1, message = "查詢失敗")
})
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "角色名", required = false, defaultValue = "張三"),
@ApiImplicitParam(name = "num", value = "序列號(hào)", required = true)
}
)
@PostMapping("/getInfo")
public TestDto getInfo(String name, Integer num) {
return new TestDto(name, num);
}
@ApiIgnore
@GetMapping("/getStr")
public String getStr(String name) {
return name;
}
}
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel( value = "角色實(shí)體類", description = "存儲(chǔ)數(shù)據(jù)并返回")
public class TestDto {
@ApiModelProperty( value = "姓名", example = "張三", hidden = false)
private String name;
@ApiModelProperty( value = "序列號(hào)", example = "1")
private Integer num;
}
到了這里，關(guān)于springboot 集成 Swagger3（速通）的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
