坚持学习第五天：SpringBoot 2.x 整合Swagger2 生成接口文档

认真是一种态度,坚持是一种品格,优秀是一种习惯！
随着技术的不断革新，目前大多数互联网公司引进了前后端分离的开发模式。前端负责页面的开发，包括页面样式以及相关接口对接；而后端则专注于后台业务的实现。这样确实极大的提高了开发效率。但同时也带了沟通上的问题，因为接口都是后台实现和提供的。那么就必须写好相应的接口文档，告知前端接口地址、接口参数规范等等。因此我们引入了swagger一个为接口文档而生的开源项目，它以注解的方式，让后端在开发过程中就可以通过简单便捷的方式完成接口文档编写。
效果如下图：

接口文档效果

基础理论

swagger常用注解及说明：
@Api():用于类，标识这个类是swagger的资源
@ApiOperation():用于方法,表示一个http请求的操作
@ApiParam():用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
@ApiModel():用于类 ,表示对类进行说明，用于参数用实体类接收
@ApiModelProperty():用于方法，字段 ,表示对model属性的说明或者数据操作更改
@ApiIgnore():用于类，方法，方法参数 ,表示这个方法或者类被忽略
@ApiImplicitParam(): 用于方法 ,表示单独的请求参数
@ApiImplicitParams(): 用于方法，包含多个@ApiImplicitParam
Tips:
若参数实体类某个参数不想显示到接口文档中，可通过ApiModelProperty实现，实现方式：
@ApiModelProperty(hidden=true)

那么我们现在就简单说说Springboot项目中如何整合进swagger2.

项目框架：

JDK 1.8
SpringBoot 2.1.5.RELEASE
Swagger 2.9.2
swagger-bootstrap-ui 1.9.4

创建项目

在坚持学习第一天中已经讲过SpringBoot项目的创建了，此处不再赘述。可直接参考。

整合swagger2

Maven依赖添加
在项目pom.xml中添加swagger2相应的依赖。

      <!-- swagger2 主要依赖 --->
      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
       <!-- swagger2 默认主题样式 --->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
       <!-- swagger2 bootstrap风格主题样式 --->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.4</version>
        </dependency>

swagger配置
在项目中添加swagger基础配置(SwaggerConfig.java)

package com.cooper.common;

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;

/**
 * Swagger配置
 */
@Configuration
public class SwaggerConfig {

    /**
     * 通过 createRestApi函数来构建一个DocketBean
     * 函数名,可以随意命名,喜欢什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cooper.module"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo());
    }


    /**
     * 构建 api文档的详细信息函数
     * @return  ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("copper_sp 接口文档")
                .version("v1.0.0")
                .description("copper_sp 接口文档")
                .build();
    }

}

启动类中指定启用Swagger
在项目启动主类添加注解@EnableSwagger2指定启用swagger.

package com.cooper;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class CooperSpApplication {

    public static void main(String[] args) {
        SpringApplication.run(CooperSpApplication.class, args);
    }

}

此时我们启动项目，访问默认接口地址：xxxx/swagger-ui.html效果如下：

默认swagger接口文档

然后我们在访问一下bootstrap风格的接口地址：
xxxx/doc.html效果如下：

bootstrap风格接口文档

至此基本的整合我们就完成了。当然部分整合时可能会出现swagger-ui.html和doc.html访问地址报404.若出现此等问题，可以尝试将这两个路由添加到springboot的资源管理中，实现方式如下：通过实现WebMvcConfigurer类后重写addResourceHandlers方式实现：


public class WebConfig  implements  WebMvcConfigurer { 

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

写个接口文档试试

上面我们已经将swagger整合到springboot中了，接下来我们就写个接口文档看看效果。

接口文档

 @ApiOperation(value = "分页获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "名称",dataType = "String"),
            @ApiImplicitParam(name = "current",value = "当前页",required = true,dataType = "int",example = "1"),
            @ApiImplicitParam(name = "size",value = "分页条数",required = true,dataType = "int",example = "10"),
    })
    @RequestMapping(value = "/list-with-page",method = {RequestMethod.GET,RequestMethod.POST})
    @ResponseBody
    public IPage<User> listWithPage(String name, Page<User> page){
        return userService.listWithPage(name,page);
    }

实际生成效果

image.png

image.png

至此springboot整合swagger2基本算完成了。我们可以稍许简单的方式编写接口文档了。更多swagger知识，待下次补充。
若有哪位好友有更方便快捷的方式欢迎赐教。