Spring Mvc和SpringBoot整合Swagger2

今天做不成的事，明天也不会做好。

---

各位同学大家好，最近项目赶进度，没有钻研技术的时间，但碰巧今天需要在Spring项目上进行SpringMvc和Swagger的整合，而第一次使用Swagger是在SpringBoot项目上，因此踩了不少的坑，于是想和大家分享一下
：关于Swagger在SpringBoot或者和SpringMvc的集成!

---

1.什么是Swagger?

1.1 背景

随着开发模式逐渐向前后端分离演变，沟通的成本逐渐增加，前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

1.2 Swagger组成

没有API文档工具之前，大家都是手写API文档的，在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏。
书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。

swagger生态使用图，红字的是swagger官方推荐的
下面再细看看swagger的生态的具体内容：
1. swagger-ui
这玩意儿从名字就能看出来，用来显示API文档的。和rap不同的是，它不可以编辑。
2. swagger-editor
就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用。
3. swagger-validator
这个小工具是用来校验生成的文档说明文件是否符合语法规定的。
4. swagger-codegen
代码生成器，脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。
有一定用处，Java系用的挺多。工业上应该不咋用。

我们主要集成的是swagger-ui，以方便我们接口的测试和管理。

2.集成方式

swagger现在有两个版本，同时对应两种集成方式；版本1的swagger需要下载swagger-ui项目并导入自己的项目，导致项目臃肿且现在已不支持使用；因此我们现在的集成是对swagger2而言；首先，我们先讲解SpringBoot项目下的集成。

2.1 SpringBoot集成

2.1.1 jar包依赖

    maven：
        <!-- swagger -->
        <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>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
         <artifactId>jackson-annotations</artifactId>
            <version>2.4.0</version>
        </dependency>

2.1.2 SwaggerConfig配置文件

@EnableSwagger2//Swagger的开关，表示我们在项目中启用Swagger
@Configuration//声名这是一个配置类
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

    //controller接口所在的包
    private String basePackage = "com.yh.controller";

    //当前文档的标题
    private String title = "headshow";

    //当前文档的详细描述
    private String description = "headshow";

    //当前文档的版本
    private String version = "V1.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(version)
                .build();
    }
}

2.1.3 Controller接口注解

@Api(value = "类描述", tags = {"显示的标签"})
@RestController
@RequestMapping(value = "/test")
public class TestController {

    @ApiOperation(value = "方法描述", produces = "application/json")
    @PostMapping(value = "/join")
    public String join(@RequestParam(required = false) String param){

        return "order/detail_add";
    }
}

好了，现在我们启动项目，访问http://localhost:项目端口/swagger-ui.html,就可以看到我们的接口文档了！

2.2 SpringMvc与swagger的集成

2.2.1 jar包依赖

    maven：
        <!-- swagger -->
        <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>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
         <artifactId>jackson-annotations</artifactId>
            <version>2.4.0</version>
        </dependency>

2.2.2 SwaggerConfig配置文件

@EnableSwagger2//Swagger的开关，表示我们在项目中启用Swagger
@Configuration//声名这是一个配置类
public class SwaggerConfig {

    //controller接口所在的包
    private String basePackage = "com.yh.controller";

    //当前文档的标题
    private String title = "headshow";

    //当前文档的详细描述
    private String description = "headshow";

    //当前文档的版本
    private String version = "V1.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(version)
                .build();
    }
}

2.2.3 Controller接口注解

@RestController
@RequestMapping(value = "/swagger")
@Api(value="user", tags = {"显示标签名"}) 
public class SwaggerController {

    @ApiOperation(value = "方法描述", produces = "application/json")
    @RequestMapping(value = "/test")
    public String test(){
        return "123";
    }

}

2.2.4 spring-mvc.xml添加标签

    <mvc:default-servlet-handler/>
    <mvc:annotation-driven/>
    <!-- spring mvc 包扫描,应该包含 springfox包 -->
    <context:component-scan base-package="springfox,.."/>

这是最重要一步，网上很多教程都没有；如果你的xml配置了<mvc:annotation-driven/>
，这里可以不用。

现在我们访问http://localhost:tomcat端口/项目名/swagger-ui.html

---

好了，做到这，关于swagger的集成算是完成了！有空也可以去研究一下swagger的其他用法，毕竟它还是能提高我们的开发效率。