SpringBoot整合Swagger2详细教程

谁践踏了优雅 2023-10-06 14:02 51阅读 0赞

##### 1. 简介 #####

随着前后端分离开发模式越来越流行，编写接口文档变成了开发人员非常头疼的事。而Swagger是一个规范且完整的web框架，用于生成、描述、调用可视化的RESTful风格的在线接口文档，并解决手写文档时编写和更新以及测试的复杂问题。

##### 2. 示例代码 #####

*  创建项目  
    ![format_png][]
 *  修改pom.xml

<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    	<modelVersion>4.0.0</modelVersion>
    	<groupId>com.c3stones</groupId>
    	<artifactId>spring-boot-swagger2-demo</artifactId>
    	<version>0.0.1-SNAPSHOT</version>
    	<name>spring-boot-swagger2-demo</name>
    	<description>Spring Boot Swagger2 Demo</description>
    
    	<parent>
    		<groupId>org.springframework.boot</groupId>
    		<artifactId>spring-boot-starter-parent</artifactId>
    		<version>2.2.8.RELEASE</version>
    		<relativePath />
    	</parent>
    
    	<dependencies>
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>2.9.2</version>
    		</dependency>
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>2.9.2</version>
    		</dependency>
    		<dependency>
    			<groupId>org.projectlombok</groupId>
    			<artifactId>lombok</artifactId>
    		</dependency>
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-web</artifactId>
    		</dependency>
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-test</artifactId>
    			<scope>test</scope>
    		</dependency>
    	</dependencies>
    
    </project>

*  创建Swagger2配置类

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;
    
    /**
     * Swagger2配置类
     * 
     * @author CL
     *
     */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
    
    	/**
    	 * 注入Docket
    	 * 
    	 * @return
    	 */
    	@Bean
    	public Docket docket() {
    		return new Docket(DocumentationType.SWAGGER_2).apiInfo(setApiInfo()).select()
    				.apis(RequestHandlerSelectors.basePackage("com.c3stones.controller")).paths(PathSelectors.any())
    				.build();
    	}
    
    	/**
    	 * 配置在线文档的基本信息
    	 * 
    	 * @return
    	 */
    	private ApiInfo setApiInfo() {
    		return new ApiInfoBuilder().title("SpringBoot整合Swagger2示例")
    				.description("<a href='https://www.cnblogs.com/cao-lei/' target='_blank'>欢迎访问我的博客</a>")
    				.termsOfServiceUrl("https://www.cnblogs.com/cao-lei/").version("V1.0").build();
    	}
    
    }

*  创建实体

import lombok.AllArgsConstructor;
    import lombok.Data;
    
    /**
     * 用户信息
     * 
     * @author CL
     *
     */
    @Data
    @AllArgsConstructor
    public class User {
    
    	/**
    	 * 用户ID
    	 */
    	private Long id;
    
    	/**
    	 * 用户名称
    	 */
    	private String username;
    
    	/**
    	 * 年龄
    	 */
    	private Integer age;
    
    }

*  创建Controller

import java.util.ArrayList;
    import java.util.List;
    
    import org.springframework.http.HttpRequest;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.ResponseBody;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.c3stones.entity.User;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import springfox.documentation.annotations.ApiIgnore;
    
    /**
     * 用户Controller
     * 
     * @author CL
     *
     */
    @Api(tags = "User / 用户信息")
    @RestController
    @RequestMapping(value = "/user")
    public class UserController {
    
    	/**
    	 * 获取用户信息
    	 * 
    	 * @param user 用户信息
    	 * @return
    	 */
    	@RequestMapping(value = "/get", method = RequestMethod.GET)
    	@ResponseBody
    	@ApiOperation(value = "获取用户信息")
    	@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, type = "Long"),
    			@ApiImplicitParam(name = "username", value = "用户名称", type = "String"),
    			@ApiImplicitParam(name = "age", value = "年龄", type = "Integer") })
    	public User get(User user) {
    		return new User(1L, "C3Stones", 23);
    	}
    
    	/**
    	 * 获取用户列表
    	 * 
    	 * @param user 用户信息
    	 * @return
    	 */
    	@SuppressWarnings("serial")
    	@RequestMapping(value = "/listData", method = { RequestMethod.GET, RequestMethod.POST })
    	@ResponseBody
    	@ApiOperation(value = "获取用户列表")
    	@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", type = "Long"),
    			@ApiImplicitParam(name = "username", value = "用户名称", type = "String"),
    			@ApiImplicitParam(name = "age", value = "年龄", type = "Integer") })
    	public List<User> listData(User user, @ApiIgnore HttpRequest request) {
    		return new ArrayList<User>() {
    			{
    				add(new User(1L, "张三", 23));
    				add(new User(2L, "李四", 24));
    				add(new User(3L, "王五", 25));
    			}
    		};
    	}
    }

*  创建启动类

import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    /**
     * 启动类
     * 
     * @author CL
     *
     */
    @SpringBootApplication
    public class Application {
    
    	public static void main(String[] args) {
    		SpringApplication.run(Application.class, args);
    	}
    
    }

##### 3. 测试 #####

*  启动项目
 *  浏览器访问

http://127.0.0.1:8080/swagger-ui.html

##### 4. 项目地址 #####

[spring-boot-swagger2-demo][]

[format_png]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTExOTA5Ny8yMDIwMDcvMTExOTA5Ny0yMDIwMDczMTE3MTY0NDkyNy0xMDE5OTU1MTk4LnBuZw?x-oss-process=image/format,png
[spring-boot-swagger2-demo]: https://github.com/C3Stones/blog