Springboot + swagger2 配置步骤及相关知识

通过学习，总结一下关于swagger2的应用场景和springboot集成swagger2的方法。

本次学习有四块

1. swagger2介绍
2. swagger2 应用场景
3. swagger2与springboot环境搭建
4. swagger2与springboot开发配置相关

• swagger2 介绍

        swagger官方网站：       https://swagger.io/

       从官网上面基本上找不到swagger的介绍，只说是API文档生成框架，是一个规范和完整的框架，

       用于生成、描述、调用和可视化Restful风格的web服务。

       有兴趣的开发者们可以到官网上看看他的应用组件等工具的描述和使用范例

• swagger2 应用场景

        正如介绍所说，如果你需要开发设计API，并且你的API需要发布给使用者来调用，如果你不想要更多的support他们在调用中遇到的各种问题，swagger正是一个这样的API文档自动生成工具，他可以定制生成你的官方API文档，并且支持各种API分类，你需要暴露的和不需要暴露的API也能够配置。还有个最大的好处是，在swagger自带的API文档页面上，用户还可以直接测试API调用，使用户更了解每个API的用途和使用方法。

       国外很多公司网站的开发环境现在基本上都支持swagger的自动文档生成。当你要跟他们公司做接口集成， 他们只需要甩给你一个他们的swagger页面，你自己就能很方便的去研究你所需要的功能接口。这样，极大的减低了开发支持人员成本。

      下图就是swagger的界面，绿色主题，包含四个部分

1.  右上角的下拉菜单文档类型选择框，默认为default类型。
2.  左上的文档说明区域，包括 文档名称，版本号，描述，文档license及连接，开发者信息及邮箱等。
3. 中间的主要文档区域，显示了所有暴露出来的API相关文档。
4. 下面的models区域，显示所有试图，模型信息。

• swagger2 与springboot环境搭建

       本节里主要以步骤的方式介绍如何搭建基于springboot的支持swagger的环境。本次开发基于IntellJ IDEA 开发工具

       1. 创建一个springboot的项目，我们只需要选择Spring Web的支持

         2. 在项目POM中导入swagger相关依赖，我们可以到mvnrepository中搜索得到我们需要的两个包，

         一个是swagger核心依赖swagger2， 还有一个就是他的ui swagger-ui（他们都是springfox下的包）

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

         3. 创建SwaggerConfig类， 标注为springboot configuration并且注解为EnableSwgger2

          4. 随手些一个HelloController，并做一些简单的rest API的方法用来测试。

              这里写了三个helloWorld的方法，第一个用了get方法，第二个第三个定义了get，post两种访问方法。

             5. 启动项目测试一下你的swagger是否能够进入界面。

                 访问 http://localhost:8080/swagger-ui.html#/， 这个是swagger-ui给的界面访问地址。你可以看到如下界面。

                因为是默认配置，所以swagger给出了所有default的参数，他给出了我自己写的hello controller的内容，也给出了

                sprintboot系统自定义的basic-error-controller。并且你们可以看到我的三个API方法，第一个只暴露了get方法调用，

               第二第三个方法暴露了get和post调用。如果你在controller里面没有指定调用方法，他会显示出所有调用方法。

              （GET, HEAD, POST, PUT, DELETE, OPTION, PATCH）

    至此，恭喜你，你已经为你的项目搭建好了swagger。但是，路漫漫其修远兮，现在只是实现了swagger默认配置。

• swagger2与springboot开发配置相关

        为了更好的使用swagger，我们需要对此进行定制化的配置，以实现我们需要的功能。比如说首先你肯定希望给自己API文档取一个高大上的名字吧，为什么总会显示“Api Documentation”，以及作者是谁，API的license，版本号等等。

       并且， 我不想整个项目的API全部被暴露出来怎么办，我只想定制化暴露我需要的API怎么办。我想要把API分类显示怎么办，接下来我们需要熟悉的就是swagger的各种配置。上一步中我们已经创建了SwaggerConfig类，现在只是一个框，我们需要往里面填东西。

       1. 配置我们的Docket。Docket在代码里面的解释是：“用于作为进入Springfox框架的主要接口的构建器。提供合理的默认设置和方便的配置方法”， swagger的很多配置都在他里面。具体配置详见下图。

          docket需要标注为bean，并且他需要确定一个文档类型，我们这里需要选择SWAGGER_2的类型。（注： documentationType有三种 SWAGGER_12表示支持sawgger1.2版本， SWAGGER_WEB表示支持spring-web 1.0, 目前我们配置的SWAGGER_2支持swagger 2.0以上。）   

        docket还需要有一个apiInfo的信息，这个apiInfo顾名思义就是API的一些信息，信息解释如图。              

          配置好了后我们重新启动就能够看到API info部分发生了变化。

        2. 添加多环境支持

        我们有时候需要分环境，并且swagger文档只需要在生产测试环境有效果，在正式环境我们不需要这些。

       所以我们就要在docket里面配置如下。

       首先我们需要在resource里面增加application-dev.properties和application-prod.properties的环境配置，并且我们在application.properties里面配置dev环境生效： spring.profiles.active=dev。

      然后我们给docket传入Environment参数，并且通过Profiles文件获取到dev的profile，然后通过环境env的acceptsProfiles去判断当前环境的profiles是否匹配，然后将得到的boolean值传入到docket的enable方法中。

这样，当dev环境的时候就会正常显示，其他环境就显示不出来。

         3. 配置扫描所支持的API。

         使用select()， select支持apis的方式和path的方式，下图配置的为apis的方式。最后我们需要build这个selcet

         下图是指定了只扫描“com.tang.swagger.controller”这个包下面的API

          api的扫描方式需要获得一个RequestHandlerSelectors， 方式有多种：

          basePackage():                     如上，扫描具体包下面的API

          any():                                    所有的扫描

          none():                                 所有的都不扫描

          withClassAnnotation():        根据类的注解来做扫描

          withMethodAnnotation():     根据方法的注解来扫描

          paths的扫描方式需要获得一个PathSelectors (也有any，none)：

         下图就是使用paths来做扫描，改次扫描是只扫描/hello开头的所有API

          ant():                扫描指定path的API

          regex():            通过正则表达式来匹配path扫描API

         最终扫描结果如下图，过滤了扫描之外的API，现在只有我HelloController里面的API在了。

          4. 配置API文档分组

             添加多个docket的bean， 并且groupName设置为不一样的name，然后在不同的doket里面配置不同的apiInfo，并且扫描不同类型的API。

                   最后得到的页面是这样的

            5.Model的生成         

            只要被扫描的API有相关的model作为返回值，我们的swagger API文档界面就会有model的展示。

            如下图，我们创建了一个简单的model User, 然后作为参数和返回值分别在controller里面使用

       

   

大概的总结就在这里，以上类容大概也能实现大多数对swagger的需求了。希望大家能够给点宝贵的意见和建议。我们共同进步。