SpringBoot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包

• Springfox-swagger2

• swagger-swagger-ui

添加Maven依赖

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

package com.example.blog.cofig;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.BuilderDefaults;
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 java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig
{
    //配置了swagger的docket的bean实例
    @Bean
    public Docket docket()
    {
       return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
    }

    //配置apiInfo
    public ApiInfo apiInfo()
    {
        /*作者信息*/
        Contact contact = new Contact("苏七","http://8.136.84.238:8080","1141793961@qq.com");

        return new ApiInfo("blog-api Documentation",
               "博客前端文档",
               "v1.0",
               "http://8.136.84.238:8080",
                contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList());
    }
}

点击docket,可以看到swagger2只能通过构造方法进行配置，因为没有set方法，并且主要设置apiInfo

package springfox.documentation.spring.web.plugins;


public class Docket implements DocumentationPlugin {
    public static final String DEFAULT_GROUP_NAME = "default";
    private final DocumentationType documentationType;
    private final List<SecurityContext> securityContexts = Lists.newArrayList();
    private final Map<RequestMethod, List<ResponseMessage>> responseMessages = Maps.newHashMap();
    private final List<Parameter> globalOperationParameters = Lists.newArrayList();
    private final List<Function<TypeResolver, AlternateTypeRule>> ruleBuilders = Lists.newArrayList();
    private final Set<Class> ignorableParameterTypes = Sets.newHashSet();
    private final Set<String> protocols = Sets.newHashSet();
    private final Set<String> produces = Sets.newHashSet();
    private final Set<String> consumes = Sets.newHashSet();
    private final Set<ResolvedType> additionalModels = Sets.newHashSet();
    private final Set<Tag> tags = Sets.newHashSet();
    private PathProvider pathProvider;
    private List<? extends SecurityScheme> securitySchemes;
    private Ordering<ApiListingReference> apiListingReferenceOrdering;
    private Ordering<ApiDescription> apiDescriptionOrdering;
    private Ordering<Operation> operationOrdering;
    private ApiInfo apiInfo;
    private String groupName;
    private boolean enabled;
    private GenericTypeNamingStrategy genericsNamingStrategy;
    private boolean applyDefaultResponseMessages;
    private String host;
    private Optional<String> pathMapping;
    private ApiSelector apiSelector;
    private boolean enableUrlTemplating;
    private List<VendorExtension> vendorExtensions;

    public Docket(DocumentationType documentationType) {
        this.apiInfo = ApiInfo.DEFAULT;
        this.groupName = "default";
        this.enabled = true;
        this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
        this.applyDefaultResponseMessages = true;
        this.host = "";
        this.pathMapping = Optional.absent();
        this.apiSelector = ApiSelector.DEFAULT;
        this.enableUrlTemplating = false;
        this.vendorExtensions = Lists.newArrayList();
        this.documentationType = documentationType;
    }


    public Docket apiInfo(ApiInfo apiInfo) {
        this.apiInfo = (ApiInfo)BuilderDefaults.defaultIfAbsent(apiInfo, apiInfo);
        return this;
    }


    ...


}

再点击apiInfo，将最下面的默认info信息复制，新建一个函数返回该信息，也就是上面SwaggerConfig的配置信息

package springfox.documentation.service;

import com.google.common.collect.Lists;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

public class ApiInfo {
    public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
    public static final ApiInfo DEFAULT;
    private final String version;
    private final String title;
    private final String description;
    private final String termsOfServiceUrl;
    private final String license;
    private final String licenseUrl;
    private final Contact contact;
    private final List<VendorExtension> vendorExtensions;

    /** @deprecated */
    @Deprecated
    public ApiInfo(String title, String description, String version, String termsOfServiceUrl, String contactName, String license, String licenseUrl) {
        this(title, description, version, termsOfServiceUrl, new Contact(contactName, "", ""), license, licenseUrl, new ArrayList());
    }

    public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) {
        this.title = title;
        this.description = description;
        this.version = version;
        this.termsOfServiceUrl = termsOfServiceUrl;
        this.contact = contact;
        this.license = license;
        this.licenseUrl = licenseUrl;
        this.vendorExtensions = Lists.newArrayList(vendorExtensions);
    }

    public String getTitle() {
        return this.title;
    }

    public String getDescription() {
        return this.description;
    }

    public String getTermsOfServiceUrl() {
        return this.termsOfServiceUrl;
    }

    public Contact getContact() {
        return this.contact;
    }

    public String getLicense() {
        return this.license;
    }

    public String getLicenseUrl() {
        return this.licenseUrl;
    }

    public String getVersion() {
        return this.version;
    }

    public List<VendorExtension> getVendorExtensions() {
        return this.vendorExtensions;
    }

    static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

访问测试 ：http://localhost:8777/swagger-ui.html ，可以看到swagger的界面

构建Docket时通过select()方法配置怎么扫描接口。

package com.example.blog.cofig;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
import springfox.documentation.builders.BuilderDefaults;
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 java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig
{
    //配置了swagger的docket的bean实例
    @Bean
    public Docket docket()
    {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                /*RequestHandlerSelectors类中的方法
                basePackages:指定要扫描的包
                any:扫描全部
                none:什么都不扫
                withMethodAnnotation:扫描方法上的注解,比如
                RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)扫描注解带有GetMapping的handler
                扫描类上的注解
                RequestHandlerSelectors.withClassAnnotation(Controller.class)扫描注解带有GetMapping的handler
                * */
                .apis(RequestHandlerSelectors.basePackage("com.example.blog.controller"))
                .build();


    }

    //配置apiInfo
    public ApiInfo apiInfo()
    {
        /*作者信息*/
        Contact contact = new Contact("苏七","http://8.136.84.238:8080","1141793961@qq.com");

        return new ApiInfo("blog-api Documentation",
               "博客前端文档",
               "v1.0",
               "http://8.136.84.238:8080",
                contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList());
    }
}

Docket类中有一个enable方法,.enable可以配置是否自动开启，默认为true

Docket类中有一个select方法

public ApiSelectorBuilder select() {
        return new ApiSelectorBuilder(this);
    }

//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by Fernflower decompiler)
//

package springfox.documentation.spring.web.plugins;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import com.google.common.collect.Iterables;
import springfox.documentation.RequestHandler;
import springfox.documentation.spi.service.contexts.ApiSelector;

public class ApiSelectorBuilder {
    private final Docket parent;
    private Predicate<RequestHandler> requestHandlerSelector;
    private Predicate<String> pathSelector;

    public ApiSelectorBuilder(Docket parent) {
        this.requestHandlerSelector = ApiSelector.DEFAULT.getRequestHandlerSelector();
        this.pathSelector = ApiSelector.DEFAULT.getPathSelector();
        this.parent = parent;
    }

    public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) {
        this.requestHandlerSelector = Predicates.and(this.requestHandlerSelector, selector);
        return this;
    }

    public ApiSelectorBuilder paths(Predicate<String> selector) {
        this.pathSelector = Predicates.and(this.pathSelector, selector);
        return this;
    }

    public Docket build() {
        return this.parent.selector(new ApiSelector(this.combine(this.requestHandlerSelector, this.pathSelector), this.pathSelector));
    }

    private Predicate<RequestHandler> combine(Predicate<RequestHandler> requestHandlerSelector, Predicate<String> pathSelector) {
        return Predicates.and(requestHandlerSelector, this.transform(pathSelector));
    }

    private Predicate<RequestHandler> transform(final Predicate<String> pathSelector) {
        return new Predicate<RequestHandler>() {
            public boolean apply(RequestHandler input) {
                return Iterables.any(input.getPatternsCondition().getPatterns(), pathSelector);
            }
        };
    }
}

里面的apis就是指定扫描的路径

paths是一个过滤器，只扫描哪些接口

                这里的可选值还有

                any() // 任何请求都扫描         

                none() // 任何请求都不扫描        

                 regex(final String pathRegex) // 通过正

则表达式控制        

                 ant(final String antPattern) // 通过ant()控制

 新建三个application.yaml文件

在application.yaml设置active: dev,就是处于开发环境下

spring:
  profiles:
    active: dev

application-dev.yaml：

server:
  port: 8777

application-prod.yaml：

server:
  port: 8776

package com.example.blog.cofig;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
import springfox.documentation.builders.BuilderDefaults;
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 java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig
{
    //配置了swagger的docket的bean实例
    @Bean
    public Docket docket(Environment environment)
    {
        //设置要显示的swagger2环境
        Profiles profiles = Profiles.of("dev","prod");


        //通过environment.acceptsProfiles(profiles)判断是否处在自己设定的环境中
        //如果环境是dev,那就是true，如果是prod就是false
        boolean environmentFlag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(environmentFlag) //是否启用swagger2
                .select() //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                /*RequestHandlerSelectors类中的方法
                basePackages:指定要扫描的包
                any:扫描全部
                none:什么都不扫
                withMethodAnnotation:扫描方法上的注解,比如
                RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)扫描注解带有GetMapping的handler
                扫描类上的注解
                RequestHandlerSelectors.withClassAnnotation(Controller.class)扫描注解带有GetMapping的handler
                * */
                .apis(RequestHandlerSelectors.basePackage("com.example.blog.controller"))
                .build();


    }

    //配置apiInfo
    public ApiInfo apiInfo()
    {
        /*作者信息*/
        Contact contact = new Contact("苏七","http://8.136.84.238:8080","1141793961@qq.com");

        return new ApiInfo("blog-api Documentation",
               "博客前端文档",
               "v1.0",
               "http://8.136.84.238:8080",
                contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList());
    }
}

所以只有在dev下，swagger2才会开启