spring boot集成Swagger

JDK 8

SPRING BOOT 2.5.3

io.springfox:springfox-swagger2:2.9.2

io.springfox:springfox-swagger-ui

com.github.xiaoymin:swagger-bootstrap-ui:1.9.6

--

 

swagger官網

偉大的Coder！

 

起步

添加依賴包：來自博客園

<!-- 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>

mvnrepository截圖：

2.9.2不是最新版了。

包依賴關係：

 

啓動項目，訪問：http://localhost:port/swagger-ui.html

彈出了一個窗口，無法關閉。

停止運行項目，纔可以關閉。來自博客園

swagger-ui.html 是一個網頁，來自下面的依賴包：爲什麼不直接使用 swagger包呢？需要UI？

 

添加了依賴包，什麼也沒做，就出現了上面的情況。來自博客園

 

接下來，添加配置。

 

配置1：空白配置

import org.springframework.context.annotation.Configuration;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

啓動項目，此時，日誌輸出下面的信息：來自博客園

pertySourcedRequestMappingHandlerMapping : Mapped URL path [/v2/api-docs] onto method 
[springfox.documentation.swagger2.web.Swagger2Controller#getDocumentation(String, HttpServletRequest)]

 

再次訪問上面的網頁 /swagger-ui.html：此時，打開了頁面，顯示了一些接口信息

最後兩個接口的響應內容是 項目的接口信息，返回後，再由頁面展示出來。來自博客園

上面的 compony-controller 是自己開發的接口，其它的是系統自動存在的，因爲配置是空白的，所以，全部都展示出來了。

點擊 compony-controller 可以查看其下的接口，點擊接口，可以查看接口的相信信息：

配置2：更多配置

SwaggerConfig.java

package org.zl.mybatis.use.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;

/**
 * Swagger配置
 * @author ben
 * @date 2021-11-25 20:37:54 CST
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

	private String appBasePackage = "org.zl.mybatis.use";
	
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				// 搜索包名：本項目基礎package
				.apis(RequestHandlerSelectors.basePackage(appBasePackage))
				// 包名下的任何路徑
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// 標題
				.title("S.B.項目")
				// 描述
				.description("Swagger使用")
				// 版本
				.version("1.0.0")
				// 聯繫人信息
				.contact(new Contact("ben", "http://localhost:10000", "ben@localhost"))
				.build();
	}
	
}

 

訪問頁面，顯示如下：沒有基礎包下的信息了，Swagger文檔展示的信息更準確了。

上面的UI看起來不太友好，於是，優秀的程序員開發了另一套UI：展示、調試（調用）接口都更爲方便。來自博客園

新UI依賴包：1.9.6是最新版，但很久沒有更新了

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

說明，com.github.xiaoymin 下 發現還有很多其它項目。

添加依賴包後，訪問：http://localhost:port/doc.html

這樣通過劃分TAB頁，頁面看起來更好看了。

注意，上面是添加依賴包，此時，前面的 /swagger-ui.html 還是可以訪問的。但是，沒有必要用兩個，那就選擇後面一個吧——刪除前面的依賴包。

 

說明，上面的配置 也是我目前使用的最新的配置。

 

在上面的Swagger的基礎上，再合理使用Swagger的註解來介紹接口，可以更好地把接口展示給調用方。

 

下面是一些示例：

注意，@Data 是 lombok註釋，提供了 getter、setter等——必須有這兩類函數纔會被 Swagger文檔判斷爲 Model（數據模型）。

@RestController
@RequestMapping(value="/api/company")
@Api(tags = {"公司接口"})
@Slf4j
public class ComponyController {

	@ApiOperation(value = "1、根據ID查詢公司")
	@ApiImplicitParams(
			@ApiImplicitParam(name = "id", value="公司ID", paramType = "query", required=true)
			)
	@GetMapping(value = "/getById")
	public CompanyVO getById(@RequestParam Integer id) {
		// TODO
		return null;
	}
	
	@ApiOperation(value = "2、根據ID查詢公司（DTO）")
	@GetMapping(value = "/getById/dto")
	public CompanyVO getById(GetByIdDTO dto) {
		// TODO
		return null;
	}
	
	@ApiOperation(value = "3、根據ID更新公司")
	@PostMapping(value="/update")
	public Integer updateCompany(@RequestBody UpdateCompanyDTO dto) {
		return null;
	}
	
}

@Data
public class GetByIdDTO {

	@ApiModelProperty(value="公司ID", required = true)
	private Integer id;
	
}

@Data
public class UpdateCompanyDTO {

	@ApiModelProperty(notes="公司ID", required = true)
	private Integer id;

	@ApiModelProperty(notes="中文名稱")
    private String nameCn;

	@ApiModelProperty(notes="英文名稱")
    private String nameEn;

	@ApiModelProperty(notes="創建時間")
    private Date foundingTime;

	@ApiModelProperty(notes="創建人")
    private String founder;
	
}

@Data
public class CompanyVO {

	@ApiModelProperty(notes="ID")
    private Integer id;

	@ApiModelProperty(notes="中文名稱")
    private String nameCn;

	@ApiModelProperty(notes="英文名稱")
    private String nameEn;

	@ApiModelProperty(notes="創建時間")
    private Date foundingTime;

	@ApiModelProperty(notes="創建人")
    private String founder;
    
}

訪問doc.html：

注意，上面的Swagger運行時，會輸出一條警告日誌：

2021-11-25 21:20:40.509  WARN 10384 --- [io-10000-exec-8] i.s.m.p.AbstractSerializableParameter    : 
Illegal DefaultValue null for parameter type integer

java.lang.NumberFormatException: For input string: ""
	at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_202]

解決：

WARN日誌來自 io.swagger 包，由於類型是 Integer導致。

此時，提升io.swagger包的日誌級別爲ERROR即可。

# application.properties中
logging.level.io.swagger=error

 

更多試驗：

1）請求參數在 請求頭中；

2）更高版本的Swagger支持；

3）支持Spring Boot的WebFlux的Swagger；

4）Swagger3 是什麼？怎麼用？

 

Swagger雖然運行起來了，但是，下一個更重要的是——熟練使用Swagger的各種註解！兩相結合，纔可以爲 調用方提供更好的接口文檔。

從此再也不用把接口文檔寫到 Word 裏面了！

 

還有一個優秀的開源軟件 swagger-admin （現已停止維護）：可以在繼承各個項目的Swagger文檔。

 

》》》全文完《《《

 

業界一定還有更高級的接口文檔吧，歡迎大家分享！

 

參考文檔

1、spring boot (2) 配置swagger2核心配置 docket

by 1點

2、【轉】集成 swagger-bootstrap-ui後訪問 doc.html頁面404

by 我家有隻小熊二

在開啓安全功能時遇到無法訪問的情況，按照本文的配置可以結局問題。

3、swagger常用註解說明

by Xiangdong_She

4、