良心巨作在职架构师带你玩全栈（5）整合swagger2

科技 08-31 来源：方正技术

一、在pom文件中添加swagger2依赖


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

二、添加config配置文件

package com.yiboliu.core.conf;

import java.util.Arrays;
import java.util.LinkedHashSet;
import java.util.Set;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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:   Swagger2Config配置文件
 * @author:        gz.fangj
 * @date:          2022年8月31日 上午10:12:22
 */
@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
 
    /**
     * 是否开启swagger配置，生产环境需关闭
     */
    @Value("${swagger.enabled}")
    private boolean enable;
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).pathMapping("/")
                .enable(enable)
                .apiInfo(this.apiInfo())
                .select() // 指定需要发布到Swagger的接口目录，不支持通配符
                .apis(RequestHandlerSelectors.basePackage("com.yiboliu.core.web"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通讯协议集合
                .protocols(this.newHashSet("https", "http"));
    }
 
    /**
     * 项目信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger Api Doc")
                .description("BookAdmin后台接口")
                .contact(new Contact("user", null, "yyjcf1986@163.com"))
                .version("BookAdmin Version: 1.0.1")
                .build();
    }
 
    @SafeVarargs
    private final  Set newHashSet(T... ts) {
        if (ts.length > 0) {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }
}

三、代码中使用

@Api：修饰整个类，描述 Controller 的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP 响应其中 1 个描述
@ApiResponses：HTTP 响应整体描述
@ApiIgnore：使用该注解忽略这个 API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

	/**
	 * 根据ID获取user对象
	 */
	@ApiOperation(value = "根据ID返回User对象")
	@RequestMapping("/findUserById")
	public Object findUserById(@ApiParam("用户ID") String userid) {
		BookUserVo user = new BookUserVo();
		user.setUserId(userid);
		user.setUserName("yiboliu");
		user.setPassword("123456");
		user.setAge(20);
		return ResponseUtil.ok(user);
	}

增加工具类

package com.yiboliu.core.vo;
/**
 * 
 * @ClassName:     BookUserVo   
 * @Description:   用户VO对象
 * @author:        gz.fangj
 * @date:          2022年8月31日 上午10:33:17
 */
public class BookUserVo {
	private String userId;
	private String userName;
	private String password;
	private int age;
	public String getUserId() {
		return userId;
	}
	public void setUserId(String userId) {
		this.userId = userId;
	}
	public String getUserName() {
		return userName;
	}
	public void setUserName(String userName) {
		this.userName = userName;
	}
	public String getPassword() {
		return password;
	}
	public void setPassword(String password) {
		this.password = password;
	}
	public int getAge() {
		return age;
	}
	public void setAge(int age) {
		this.age = age;
	}
}