通过Swagger2生成、管理接口文档

    在开发团队中，优质的接口文档不仅仅可以大量减少工作中的沟通成本，对于离职人员的工作交接与新入职人员的快速上手都有很大的帮助；传统的做法不外乎由开发人员按照规定格式编辑一份RESTful API文档来记录所有接口的细节，并在本地保存，在公司的程序员之间代代相传。

    很明显这种做法存在着弊端：

• 不通服务，不通项目模块接口众多且细节复杂，需要考虑的情况也有很多，如：http的请求类型，头部信息；接口不通参数代表的不通意义等；想要高质量的完成这样的文档并同时撸代码无外乎多一份工作负担；
• 难以维护；随着需求的更改与项目的优化，接口不可避免的要进行改动，与此同时接口文档也要进行同步的修正，很容易出现接口与实际文档出现不匹配的问题；

    既然是传统方法那么必然存在着非传统方法，Swagger2就是为此类问题而生的；Swagger2作为一个规范性的完整框架，可以用于生成，描述，调用，实时更新可视化RESTful模式的文档；

SpringBoot 集成 Swagger2

Swagger官方网站：

swagger.io

GitHub Swagger2项目,有详细的讲解：

github.com/SpringForAl…

在pom.xml中添加Maven依赖：

<dependencies>
    <!-- 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>
​
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>
</dependencies>

创建 Swagger2Configuration Swagger的配置文件：

@Configuration  
@EnableSwagger2
public class Swagger2Configuration {
​
   //api接口包扫描路径
   public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.xxx.package";
​
   public static final String VERSION = "1.0.0";
​
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)) 
                   .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                   .build();
   }
​
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
                   .title("node-1") //设置文档的标题
                   .description("node-1 description") // 设置文档的描述                   
                   .version(VERSION) // 设置文档的版本信息
                   .termsOfServiceUrl("http://www.xxx.com") // 设置文档的License信息
                   .build();
   }
}

@Configuration Spring 加载该配置类

@EnableSwagger2 启用Swagger2

@Api 用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源

@ApiOperation 用于方法，表示一个http请求访问该方法的操作

@ApiModel 用于响应实体类上，用于说明实体作用

@ApiModelProperty 用在属性上，描述实体类的属性

@ApiImplicitParams 用在请求的方法上，包含多@ApiImplicitParam

@ApiImplicitParam 用于方法，表示单独的请求参数

@ApiParam 用于方法，参数，字段说明 表示对参数的要求和说明、

@ApiResponse 用在请求的方法上，表示不同的响应

@ApiIgnore 用于类或者方法上，不被显示在页面上

@Profile({"dev", "test"}) 用于配置类上，表示只对开发和测试环境有用

    这样基本上就大功告成啦，启动SpringBoot项目，访问地址：

    http://项目地址/swagger-ui.html

    就可以看到编辑的接口文档啦~

    不要问为什么没有图，当然是因为我懒得撸一遍Swagger......

    当然这只是单一服务的接口文档，若存在各服务文档地址不统一，无法集中管理等问题欢迎留言，不过这样是不是也比传统的手撸文档方便多了呢 ？

    祝各位自动化接口文档管理愉快。