一文搞懂Spring Boot集成Swagger2，以及Swagger常用注解说明和错误处理

一、背景

    我们在做前后端项目过程中，经常需要需要与前端同事对接，提供接口文档。最开始我们采用word文件的方式，在里边编写api 地址、参数、请求类型、请求和响应示例等。每次开发完一个接口，还需要编写接口规范文档，想想都觉得可怕。有些人可能觉得不可思议，但是确实存在。好多传统的软件项目，在不同团队、不同公司之间依然采用此种方式。

    Swagger作为一款侵入式的接口文档生成插件，很好的解决编写接口文档的痛苦。我经常在自己的项目和团队协作开发中使用，但是一直没有完整的记录过集成方式、使用过程、以及可能遇到的坑。刚好今天又要在自己开发的SpringBoot + layui的防wordpress博客系统中集成Swagger2，因此完成的记录一下使用过程，以备后续忘记了能有笔记翻阅。（毕竟这东西也不是天天集成，一个项目也就一次）。

二、创建Spring Boot项目

    首先，我们创建一个maven项目，然后在里边集成Spring Boot。具体创建过程，可查看Spring Boot官网的样例，都很详细。因为这里只记录Swagger相关集成和使用，因此不再详细介绍Spring Boot项目相关创建。

    为了方便，贴一下Spring Boot官网创建地址：https://spring.io/quickstart

三、加入Swagger2 相关依赖

<!-- 集成 swagger 测试接口 -->
<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>

四、添加Swagger配置Configuration

/**
 * swagger配置类
 * Created by Administrator on 2020/03/19.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xblog.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(
                        new ApiInfoBuilder()
                                .title("程序员刊-Api")
                                .description("程序员刊-Api-接口文档")
                                .version("1.0")
                                .contact(new Contact("程序员刊-个人博客","www.cxyk.net","xuebin@163.com"))
                                .license("The Apache License")
                                .licenseUrl("http://www.cxyk.net")
                                .build()
                );
    }
}

五、创建接口Controller，并添加相关注解

六、启动服务，访问http://127.0.0.1:9001/swagger-ui.html

七、Swagger2 相关注解说明

• @Api注解可以用来标记当前Controller的功能。
• @ApiOperation注解用来标记一个方法的作用。
• @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
• @ApiImplicitParams：当参数是多个时，可以使用该注解。这个注解中可以定义多个@ApiImplicitParam注解。
• @RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
• @ApiModel 表述实体相关字段说明。

八、异常处理

1、访问swagger页面报404错误

    当你的Spring Boot中实现了拦截器WebMvcConfigurationSupport，需要配置静态资源访问路径。否则访问swagger页面时会报404。具体代码如下：

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

2、访问页面时被安全校验拦截

    当集成了Spring Security权限控制时，需要重写configure方法配置忽略swagger相关文件。代码如下：

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");
}

九、最后

    至此，Spring Boot集成Swagger2就告一段了，可以访问api页面直接测试了。postman都不用安装了。

    个人经验，有不足之处，欢迎评论指出。谢谢。

    欢迎关注我的个人公众号（cxyknet），不定期分享技术热点、框架原理源码阅读、资料干货。

最后

以上就是多情蜜粉为你收集整理的一文搞懂Spring Boot集成Swagger2，以及Swagger常用注解说明和错误处理的全部内容，希望文章能够帮你解决一文搞懂Spring Boot集成Swagger2，以及Swagger常用注解说明和错误处理所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。