需求背景

Springboot集成：Swagger集成用法，本篇介紹Swagger2

問題痛點

手寫api文檔的幾個痛點：

當接口文檔需要更新時，需要再次發送一次給前端，文檔更新交流不是非常及時，比如showdoc

不能直接在線測試接口，通常需要使用其他工具，比如postman

接口文檔太多，不好管理

Swagger就是用來解決這個問題（Swagger也不是說就最好，比如不好的點就是代碼侵入性比較強）

技術點

1. 集成swagger依賴組件

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

2. 使用Swagger配置類

代碼演示

1. 項目目錄結構

2. pom.xml依賴組件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<parent>
		<groupId>com.md</groupId>
		<artifactId>spring-boot2-parent</artifactId>
		<version>0.0.1-SNAPSHOT</version>
		<relativePath>../pom.xml</relativePath>
	</parent>

	<artifactId>spring-boot2-swagger</artifactId>
	<packaging>jar</packaging>

	<name>spring-boot2-swagger</name>
	<description>Spring Boot, MVC, Rest API for App</description>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.version>
		<swagger.version>2.9.2</swagger.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<!-- 構建成可運行的Web項目 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>net.sf.json-lib</groupId>
			<artifactId>json-lib-ext-spring</artifactId>
		</dependency>
		<!-- swagger集成 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${swagger.version}</version>
		</dependency>
		<!-- 默認swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>${swagger.version}</version>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

3. 新建Swagger配置類

SwaggerConfig.java

package com.md.demo;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	/**
	 * 創建一個Docket對象 調用select()方法， 生成ApiSelectorBuilder對象實例，該對象負責定義外漏的API入口
	 * 通過使用RequestHandlerSelectors和PathSelectors來提供Predicate，在此我們使用any()方法，將所有API都通過Swagger進行文檔管理
	 * 
	 * @return
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo()).select()
				//如果不想將所有的接口都通過swagger管理的話，可以將RequestHandlerSelectors.any()修改爲RequestHandlerSelectors.basePackage()
				//.apis(RequestHandlerSelectors.any())
				.apis(RequestHandlerSelectors.basePackage("com.md"))
				.paths(PathSelectors.any())
				.build();
	}

	@SuppressWarnings("deprecation")
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// 標題
				.title("SpringBoot2 中使用Swagger2 構建RESTful APIs")
				// 簡介
				.description("This a demo for Swagger2")
				// 服務條款
				.termsOfServiceUrl("https://blog.csdn.net/hemin1003")
				// 作者個人信息
				.contact("Minbo.He")
				// 版本
				.version("1.0").build();
	}
}

4. 設置靜態資源訪問

WebConfig.java（如果不用攔截器，則可以去掉MyHttpInterceptor類）

package com.md.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * 攔截器定義
 * 
 * @author Minbo.He
 */
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {

	// 讓bean提前加載，讓攔截器中的@Autowired生效
	@Bean
	public HandlerInterceptor getMyInterceptor() {
		return new MyHttpInterceptor();
	}
	
	@Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 解決 swagger-ui.html 404報錯
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
              registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

        }

	/**
	 * 可定義多個攔截器
	 */
	@Override
	public void addInterceptors(InterceptorRegistry registry) {
		// 定義過濾攔截的url名稱，攔截所有請求
		registry.addInterceptor(this.getMyInterceptor()).addPathPatterns("/**");
		super.addInterceptors(registry);
	}

}

5. 編寫接口swagger相關內容

InitRest.java

package com.md.demo.rest;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.md.demo.util.JsonResult;
import com.md.demo.util.ResultCode;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

/**
 * @author Minbo
 */
@RestController
public class InitRest {

	protected static Logger logger = LoggerFactory.getLogger(InitRest.class);

	/**
	 * http://localhost:9090/hello
	 * 
	 * @return
	 */
	@ApiOperation(value = "/hello 歡迎入口", httpMethod = "GET")
	@RequestMapping(value = "/hello")
	public String hello() {
		logger.info("hello");
		return "Hello greetings from spring-boot2-swagger";
	}

	@ApiOperation(value = "/getUserName 根據用戶id獲得用戶的姓名", notes = "id不能爲空", httpMethod = "GET")
	@ApiImplicitParam(dataType = "string", name = "userId", value = "用戶id", required = true)
	@RequestMapping(value = "/getUserName")
	public JsonResult getUserName(String userId) {
		String result = "hello " + userId + "，name=張三";
		return new JsonResult(ResultCode.SUCCESS, result);
	}

	/**
	 * Swagger註解用法：
	 * 
	 * @Api：修飾整個類，描述Controller的作用
	 * @ApiOperation：描述一個類的一個方法，或者說一個接口
	 * @ApiParam：單個參數描述
	 * @ApiModel：用對象來接收參數
	 * @ApiProperty：用對象接收參數時，描述對象的一個字段
	 * @ApiResponse：HTTP響應其中1個描述
	 * @ApiResponses：HTTP響應整體描述
	 * @ApiIgnore：使用該註解忽略這個API
	 * @ApiError ：發生錯誤返回的信息
	 * @ApiImplicitParam：一個請求參數
	 * @ApiImplicitParams：多個請求參數
	 */
}

每一個註解，可以直接選中註解，然後點擊進去源碼中進行查看，用法很簡單

例如：@ApiOperation註解源碼用法

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

點擊init-rest欄，可以看到定義的接口

點擊進去/getUserName方法，點擊“Try it out”，輸入用戶id：test，點擊執行Execute，即可進行在線接口測試

附加用法

如果覺得默認官方UI不好用，則可以使用第三方UI組件（推薦此組件）

1. 集成pom組件

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

2. 處理WebConfig配置

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解決 swagger-ui.html 404報錯
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

        // 解決 doc.html 404 報錯
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

    }

3. Application啓動類，增加@EnableSwaggerBootstrapUI註解

package com.md.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;

/**
 * 程序主入口
 * 
 * @author Minbo
 *
 */
@SpringBootApplication
@EnableSwaggerBootstrapUI
public class Application {

	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}
}

4. 啓動項目，訪問：http://localhost:9090/doc.html

在線接口測試

完整源碼下載

我的Github源碼地址：

https://github.com/hemin1003/spring-boot-study/tree/master/spring-boot2-study/spring-boot2-parent/spring-boot2-swagger

常見問題

問題：

項目啓動後，http://localhost:9090/swagger-ui.html 或 http://localhost:9090/doc.html 界面訪問不了

解決方案：

增加WebConfig配置，進行資源處理即可，具體代碼如下

package com.md.demo;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * @author Minbo.He
 */
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {

	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		// 解決 swagger-ui.html 404報錯
		registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

		// 解決 doc.html 404 報錯
		registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

	}
}

下一章教程

SpringBoot從入門到精通教程（二十五）- Mybatis-Plus快速開發框架用法

該系列教程

SpringBoot從入門到精通教程

至此，全部介紹就結束了

------------------------------------------------------

關於我（個人域名）

我的開源項目集Github

期望和大家一起學習，一起成長，共勉，O(∩_∩)O謝謝

歡迎交流問題，可加個人QQ 469580884，

或者，加我的羣號 751925591，一起探討交流問題

不講虛的，只做實幹家

Talk is cheap，show me the code

SpringBoot從入門到精通教程（二十四）- Swagger集成用法

需求背景

問題痛點

技術點

代碼演示

附加用法

完整源碼下載

常見問題

下一章教程

該系列教程

《Python進階》學習筆記

Leetcode 3161. 物塊放置查詢

leetcode 60 排列序列

一個docker容器暴露多個端口

微服務實踐之使用 Visual Studio 2022 調試Dapr 應用程序

wpf附加屬性理解 WPF附加屬性

【總結】SQL性能優化技巧整理彙總

SpringBoot從入門到精通教程（二十七）- @Valid註解用法詳解+全局處理器Exception優雅處理參數驗證用法

微服務架構實戰 - 我的經驗分享總結2019（系統架構師）架構演進過程-從信息流架構到電商中臺架構

SpringBoot從入門到精通教程（三十二）- MybatisPlus框架動態數據源用法（支持多個DB，動態切換數據源）

SpringBoot從入門到精通教程（二十）- 分佈式鎖用法（基於Redis實現）

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結