本文旨在介绍在现有springboot项目中配置swagger2,以及一些常见问题解决方法。

一、配置步骤

1、添加Swagger依赖，在pom.xml中添加以下配置

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.7.0</version>
</dependency>

2、配置Application Class 对Swagger的支持

@EnableSwagger2
public class DemoApplication extends WebMvcConfigurerAdapter {

    public static void main(String[] args) {
        SpringApplication.run(DataGovernanceApplication.class, args);
    }
    @Override
    public void addCorsMappings(CorsRegistry registry) {

        registry.addMapping("/**")
                .allowCredentials(true)
                .allowedHeaders("*")
                .allowedOrigins("*")
                .allowedMethods("*");
    }
}

3、自定义权限配置

在pom.xml中加入security依赖

<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

禁用默认的权限配置

@SpringBootApplication(exclude = { SecurityAutoConfiguration.class })
@EnableSwagger2
public class DataGovernanceApplication extends WebMvcConfigurerAdapter {

至此访问http://localhost:8080/swagger-ui.html即可

swagger页面

二、swagger 个性化配置

新建config包，写入SpringFoxConfig配置类：

package com.demo.sample.config;

import io.swagger.annotations.ApiOperation;
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;

@Configuration
@EnableSwagger2
public class SpringFoxConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Data Governance RESTful API")
                .version("1.0")
                .description("API 描述")
                .build();

    }
}

其中.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))是选定有Api注解的接口类，也可以制定包的路径来选择。.apiInfo()是定义一些我们项目的描述信息，可以根据实际需要在参数中修改。需要注意的是配置类的头部需要加上@Configuration，声明配置类，以及@EnableSwagger2加载swagger的一些相关配置。

三、常见问题

1、启动报如下错误

org.springframework.context.ApplicationContextException: Unable to start web server; nested exception is org.springframework.context.ApplicationContextException: Unable to start ServletWebServerApplicationContext due to missing ServletWebServerFactory bean.
    at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.onRefresh(ServletWebServerApplicationContext.java:156)
    at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:543)
    at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:141)
    at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:744)
    at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:391)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:312)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1215)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1204)

愿意是添加了spring-boot-starter-security但未禁用默认的自动依赖导致，排除SecurityAutoConfiguration配置即可，

@SpringBootApplication(exclude = { SecurityAutoConfiguration.class })

2、出现Unable to infer base url.

Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually:
需要在SpringBoot的启动Application前面加上 @EnableSwagger2注解；

Spring Boot 中配置Swagger2