spring boot 整合swagger

一、导入依赖

        <!--swerger相关配置-->
        <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>

二、新建SwaggerConfigProperties配置类

import lombok.Data;
import lombok.ToString;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@Data
@ToString
@Validated
@ConfigurationProperties(prefix = "xycs.swagger")
public class SwaggerConfigProperties {

    private boolean enabled = false;
    private String pathRegex = "/.*";
    private String pathMapping = "/";
    private String basePackage = "com.jiuyect";
    private String termsOfServiceUrl="no content";       // 隐私条款说明URL地址
    private String contactName="";             // 联系人姓名
    private String contactUrl="no url";              // 联系人URL
    private String contactEmail="736421789@qq.com";            // 联系人Email地址
    private String license="license info";                 // License协议
    private String licenseUrl=" http://google.com/ncr";              // License协议地址

    private String version="1.0.0";     // API 版本号
    private String title="learn swagger";       // API 标题
    private String description="shixun description"; // API 详细描述信息
}

三、配置文件

#swagger配置
xycs:
  swagger:
    title: 环保卫士-客户端-接口文档
    contactName: 郭建伟、李磊、刘平
    contactEmail: 736421789@qq.com
    #需要生成的项目目录
    basePackage: cn.suse.edu.wasterecovery.controller.web

 

四、新建SwaggerAutoConfiguration配置类

import com.google.common.base.Predicates;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.AutoConfigureAfter;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.http.ResponseEntity;
import org.springframework.util.StopWatch;
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;
import javax.annotation.PostConstruct;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
@ConditionalOnWebApplication
@ConditionalOnClass(Docket.class)
@Profile("!product")
@ConditionalOnProperty(prefix = "xycs.swagger", name = "enabled", havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(SwaggerConfigProperties.class)
@AutoConfigureAfter(WebMvcAutoConfiguration.class)
@Slf4j
public class SwaggerAutoConfiguration {

    private SwaggerConfigProperties configProperties;
    @Autowired
    public SwaggerAutoConfiguration(SwaggerConfigProperties properties) {
        this.configProperties = properties;
    }

    @PostConstruct
    public void validate() {
        log.info("===>> Swagger auto config : {}", this.configProperties);
    }

    @Bean
    public Docket swaggerSpringfoxDocket() {
        log.debug("Starting Swagger");
        StopWatch watch = new StopWatch();
        watch.start();
        Contact contact = new Contact(
                configProperties.getContactName(),
                configProperties.getContactUrl(),
                configProperties.getContactEmail());

        ApiInfo apiInfo =
                new ApiInfoBuilder().title(configProperties.getTitle())
                        .contact(contact)
                        .description(configProperties.getDescription())
                        .termsOfServiceUrl(configProperties.getTermsOfServiceUrl())
                        .version("v1.0")
                        .build();


        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .forCodeGeneration(true)
                .genericModelSubstitutes(ResponseEntity.class)
                .ignoredParameterTypes(java.sql.Date.class)
//                .directModelSubstitute(java.time.LocalDate.class, java.sql.Date.class)
//                .directModelSubstitute(java.time.ZonedDateTime.class, Date.class)
//                .directModelSubstitute(java.time.LocalDateTime.class, Date.class)
                .select()
                .apis(RequestHandlerSelectors.basePackage(configProperties.getBasePackage()))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                .paths(regex(configProperties.getPathRegex()))
                .build();
        watch.stop();
        log.info("Started Swagger in {} ms", watch.getTotalTimeMillis());
        return docket;
    }
}

五、controller

    @ApiOperation(value = "swagger测试", notes = "swagger测试", protocols = "application/json")
@ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "String", paramType = "query"),
    })
    @GetMapping("/test")
    String test(String username){
        return "测试";
}