基于springboot+maven的swagger2安装教程

在前后端分离的模式下，一个清晰地api文档是必不可少的。而swagger就是一个非常容易搭建的api文档，只需要通过简单的配置就可以自动生成api文档。

 

▍前提条件

首先需要新建一个springboot+maven的项目。

 

▍大致安装流程

1、在pom.xml注入依赖；

2、新建swagger2配置文件并配置相关信息；

3、在controller中配置接口信息。

4、启动项目并查看api文档。

 

▍注入依赖

打开pom.xml文件，加入以下两个依赖项，然后点击右键：Maven=》Download S… AND D…，下载两项依赖，保证这两项依赖的信息不为红色即完成。

<!--添加Swagger依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<!--添加Swagger-UI依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

 

▍配置swagger2

新建config包（新建在跟controller、service等包同等位置即可），在config包下新建SwaggerConfig.java文件，导入以下配置，并根据自身实际修改相关内容即可。

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


// 标记配置类
@Configuration
// 开启在线接口文档
@EnableSwagger2
public class Swagger2Config {

    /**
     * @Description:swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 配置到项目的controller包
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any()).build();
    }

    /**
     * @Description: 构建api文档的信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx项目文档标题")
                .description("xxx项目文档描述")
                .contact(new Contact("xxx开发者称呼", "xxx.com网站", "xxx@qq.com邮箱"))
                // 定义版本号
                .version("版本号:xx.x").build();
    }
}

 

▍在controller类中添加配置信息

在controller类中参考如下信息配置：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;

import javax.servlet.http.HttpServletRequest;
import java.util.List;

@Controller
@RequestMapping("/contact")
// value：controller名称；tags：controller标签
@Api(value = "联系人接口", tags = "联系人接口")
public class BaseInfoController {
    @Autowired
    private BaseInfoService baseInfoService;

    @Autowired
    private HostHolder hostHolder;
    
    // value：接口名称；notes：接口描述
    @ApiOperation(value = "联系人列表", notes = "获取联系人列表")
    // 有多个参数时，需要使用@ApiImplicitParams，只有一个参数使用@ApiImplicitParam即可，没有参数不需要配置
    @ApiImplicitParams({
            @ApiImplicitParam(name="pageNum", value = "页数", dataType = "int", paramType = "query", required = true),
            @ApiImplicitParam(name="pageSize", value = "每页的数据量", dataType = "int", paramType = "query", required = true)
    })
    // 使用相应的请求mapping
    @GetMapping("/list")
    public List<BaseInfo> getContactList(@RequestParam("pageNum") Integer pageNum,
                                         @RequestParam("pageSize") Integer pageSize){
        Integer userId = hostHolder.getUser().getId();
        List<BaseInfo> list = baseInfoService.getContactListByUserId(userId, pageNum, pageSize);
        return list;
    }
}

效果演示：

上面的配置只用到了部分的swagger2配置组件，更多组件的应用参考：https://www.jianshu.com/p/f30e0c646c63。

 

▍启动项目并访问swagger-ui

本项目在application.properties中配置的访问端口为8080，所以在浏览器中访问以下页面即可。

http://localhost:8080/swagger-ui.html

 

▍报错

如果按照上述流程完整执行后，却无法访问到页面，并且在后台报以下错误，请浏览解决方案。

No mapping for GET /swagger-ui.html

 

▍解决方案

在config包中新建一个WebMvcConfig.java文件，并将下面代码复制到该文件中，然后重新启动项目，即可访问到页面。

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

 

▍备选解决方案

其实在摸索出上面的解决方案之前，我还尝试过以下两种解决方案，但是都没有成功。如果你在尝试了上面的解决方案后没有生效，可以尝试一下以下两种备选方案，但是成功概率不高。

 

▍解决方案参考链接

我的解决方案参考了以下网址：

https://www.cnblogs.com/xingzc/p/8656088.html