SpringBoot项目引入Swagger2

SpringBoot项目引入Swagger2

前言

随着潮流发展，越来越多公司引入前后端分离的概念，前后端各司其职专注于各自的技术开发。这种情况下接口文档就显得尤为重要，word版接口文档，每次改动都需要重新修改并分发项目组每位成员，维护成本较高且占用开发时间，这个时候就一项技术能直接将这一步省却。swagger2就是在这种情况下越发火热起来。

• 成品样式展示
  

引入swagger2

pom文件引入相关资源

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

配置swagger2配置类

• SwaggerConfig.java

package com.yc.framework.conf;

import com.fasterxml.classmate.TypeResolver;
import com.yc.consts.ResConst;
import com.yc.domain.ResContent;
import com.yc.domain.ResPageContent;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.AlternateTypeRules;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.schema.WildcardType;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.net.InetAddress;
import java.net.UnknownHostException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.Callable;

/**
 * @author Lee
 * <p>
 * http://localhost:8080/doc.html
 * </p>
 */
@Configuration
@EnableSwagger2
@Profile({"dev","test"})
public class SwaggerConfig {

    @Value("${server.port:8080}")
    private String serverPort;

    @Bean
    public Docket createRestApi(TypeResolver typeResolver) throws UnknownHostException {
        //添加全局响应状态码
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        Arrays.stream(ResConst.values()).forEach(errorEnums -> {
            responseMessageList.add(
                    new ResponseMessageBuilder().code(errorEnums.getCode()).message(errorEnums.getMessage()).responseModel(
                            new ModelRef(errorEnums.getMessage())).build()
            );
        });

        return new Docket(DocumentationType.SWAGGER_2)
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .apiInfo(apiInfo())
                .host(InetAddress.getLocalHost().getHostAddress() + ":" + serverPort)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yc.controller"))
                .paths(PathSelectors.any()).build()
                .alternateTypeRules(
                        AlternateTypeRules.newRule(typeResolver.resolve(Callable.class,
                                typeResolver.resolve(ResContent.class, WildcardType.class)
                                ),
                                typeResolver.resolve(WildcardType.class)
                        ),
                        AlternateTypeRules.newRule(typeResolver.resolve(Callable.class,
                                typeResolver.resolve(ResPageContent.class, WildcardType.class)
                                ),
                                typeResolver.resolve(WildcardType.class)
                        )
                );
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Lee的博客")
                .description("Lee的博客")
                .termsOfServiceUrl("https://blog.csdn.net/David_FY")
                .contact(new Contact("Lee", "https://blog.csdn.net/David_FY", "*@qq.com"))
                .version("1.0.0").build();
    }

}

• ResConst.java

package com.yc.consts;

import lombok.Getter;

/**
 * @author Lee
 * @version 1.0
 */
public enum ResConst {
    /**
     * 成功
     */
    OK(200,"成功"),
    UNAUTHORIZED_ERROR(401, "未授权"),
    FORBIDDEN_ERROR(403, "拒绝访问"),
    NOT_FOUND_ERROR(404, "404 not found"),
    METHOD_NOT_ALLOWED(405, "不允许此方法"),
    SYSTEM_ERROR(500, "服务繁忙，请稍后再试"),
    ;

    @Getter
    private int code;
    @Getter
    private String message;

    ResConst(int code, String message) {
        this.code = code;
        this.message = message;
    }
}

• 这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。
• 至此Swagger2就算配置成功了。
• 启动项目，输入http://localhost:8080/doc.html即可访问swagger2