导读

我们知道在微服务架构下，软件系统会被拆分成很多个独立运行的服务，而这些服务间需要交互通信，就需要定义各种各样的服务接口。具体来说，在基于Spring Cloud的微服务模式中，各个微服务会基于Spring MVC的Controller定义多个该微服务需要向外部发布的接口。

根据各个微服务功能边界定义的不同，有些微服务会提供与具体业务相关的接口，如支付接口账户接口等；而有些微服务则会提供一些公共性质的服务接口，如短信接口统一认证接口之类。而这些微服务往往又是由多个不同的团队在开发维护，传统方式下服务接口的定义往往需要服务提供方提供良好的可阅读性比较高的接口文档才可以比较方便地对接和测试，而事实上，随着时间的推移人员的迭代更新，很多情况下这些早期的接口文档往往很快就会因为无人维护而过时，即便不过时，微服务模式下这样的方式也会因为服务接口文档太多而让开发人员显得抓狂！

那么有没有一种更便捷地方式，可以让开发接口的同时，自动就能生成与服务接口高度一致的文档来呢？答案是有的，接下来就和大家一起聊聊到底有什么样方式可以让微服务的接口管理变得更加容易些！

接口管理方式介绍

事实上，市面上已经有多种开源项目提供了这样的支持！如：SwaggerApiDocRAPDOCLeverCrapApi等，这些项目都提供了对于Api在线文档的管理功能，那么在Spring Cloud体系中哪一种方式更加适合呢？下面，我们一起来对比下这些项目的优缺点。

1. Swagger

Swagger是一款基于YAMLJSON语言的文档在线生成和代码自动生成的工具。它的优点如下：

• 它可以直接嵌入在Spring Boot项目中，通过开发时编写注释，从而自动生成接口文档，实现代码与文档的高度一致；
• 可以分析接口的结构，并且还可以通过发起请求来验证接口的正确性；
• 它提供了多种编程语言的前后端分离解决方案，支持根据定义的接口导出各种语言的服务端或客户端代码 ；
• 它还包括了Swagger Editor，这是使用yaml语言的Swagger API的编辑器，支持导出yaml和json格式的接口文件；
• 包含了Swagger UI，它可以将Swagger Editor编辑好的接口文档以html的形式展示出来；
• 免费开源，支持国际化，生态丰富社区活跃；

它的缺点是：

• 对代码有侵入性；
• 不同项目的Swagger接口文档是分离的，需要到不同的地方去找；
• Swagger UI展现出来的接口文档缺乏分类，使用体验比较差；
• 不同项目的接口文档没有权限管理，缺少Mock；

2. ApiDoc

ApiDoc是一款轻量级的类似于Swagger的在线文档生成工具。其缺点也类似于Swagger，接口管理自动测试等功能也比较弱，并且其社区生态国际化方面都还不如Swagger。

3. RAP

RAP是一个可视化接口管理工具，它可以通过分析接口结构，动态生成模拟数据，校验真实接口正确性，围绕接口定义，通过一系列自动化工具提升微服务模式下的协作效率。

它的优点如下：

• 支持项目管理团队管理文档版本管理；
• 支持Mock测试数据；
• 阿里大厂出品，在阿里巴巴内部得到实践；
• 支持接口检索；
• 可以分析接口结构，发起请求校验接口的正确性；
• 免费开源

缺点如下：

• 文档和接口分离，很容易出现不一致的现象；
• 每个接口都需要手工编辑；
• 后端采用nodejs编写，与基于Java的Spring Cloud技术栈不一致；

4. DOCLever

DOCLever也是一个免费开源的接口管理工具，它的优点如下：

• 支持项目管理团队管理文档工具丰富；
• 支持丰富的Mock测试数据；
• 用户案例也比较丰富：滴滴美团58同城同城旅游等；
• 支持接口检索；
• 可以分析接口的结构发起请求校验接口正确性参数也很丰富；
• 支持复杂场景的自动化测试，比如获取验证码登陆，获取订单列表，甚至获取某个特定订单详情等上下文关联的操作；

缺点如下：

• 文档和接口分离，很容易出现不一致的现象；
• 每个接口都需要手工编辑；
• 后端也是采用nodejs编写，与Spring Cloud的Java技术栈不符；

5. CrapApi

优点如下：

• 支持项目管理团队管理文档版本管理；
• 支持Mock测试数据；
• 支持接口检索；
• 可以分析接口结构发起请求校验接口的正确性；
• 支持接口监控设置报警规则，接口不可用时及时通知服务负责人；
• 后端基于Java开发，与Spring Cloud技术栈Java匹配；
• 免费开源；

缺点：

• 文档和接口分离，很容易出现不一致的现象；
• 每个接口都需要手工编辑；
• 使用案例较少，功能不够完善，可能会有很多坑；

6. Spring Cloud集成Swagger

通过对上述开源项目的分析，除Swagger外其余项目采取的都是文档和代码分离的方式，虽然这样会减少对代码的侵入，但是也会造成文档和代码的不一致现象，所以在基于Spring Cloud的微服务项目中，我们选择Swagger作为微服务接口管理工具。

那么基于Spring Boot的Spring Cloud微服务该如何集成Swagger呢？

①. 在Spring Boot微服务项目中引入Maven依赖：

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

②. 创建Swagger2配置类：

@Configuration
@EnableSwagger2
@Profile("!production")
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
        .groupName("Api")
        .select()
        .apis(withClassAnnotation(RestController.class))
        .build()
        .globalOperationParameters(commonParameters())
        .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        .title("Api")
        .version("1.0.0-SNAPSHOT")
        .build();
    }
    private List<Parameter> commonParameters() {
        List<Parameter> parameters = Lists.newArrayList();
        parameters.add(new ParameterBuilder()
        .name("war")
        .description("backdoor 在测试环境绕过鉴权")
        .modelRef(new ModelRef("string"))
        .parameterType("query")
        .required(false)
        .defaultValue("war123")
        .build());
        parameters.add(new ParameterBuilder()
        .name("uid")
        .description("backdoor 设定的用户ID")
        .modelRef(new ModelRef("string"))
        .parameterType("query")
        .required(false)
        .defaultValue("1000053")
        .build());
        parameters.add(new ParameterBuilder()
        .name("Authorization")
        .description("生产环境中，需要传递的用户当前 Token")
        .modelRef(new ModelRef("string"))
        .parameterType("header")
        .required(false)
        .defaultValue("Bearer XXXXX")
        .build());
        return parameters;
    }
}

以上配置类中，我们可以通过@Profile("!production")注解指定生效的环境，如这里我们设置除在生产环境外，其他环境都生效。

③. 添加文档内容

在完成上述配置后，其实已经可以生产文档内容了，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，多用户并不友好，为了让文档更加易于阅读和理解，我们可以通过Swagger注解来增加一些说明。这些注解主要有：

• @Api：用在类上，说明该类的作用。
• @ApiOperation：注解来给API增加方法说明。
• @ApiImplicitParams : 用在方法上包含一组参数说明。
• @ApiImplicitParam：用来注解来给方法入参增加说明。
• @ApiResponses：用于表示一组响应。
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。
• @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

接下来，我们通过一个实际的微服务接口定义案例来演示下：

@Api(value = "运维端系统用户层外部接口", description = "用于组装直接面向运维App端相关服务")

以上我们在微服务下定义了一个用户注册接口，此时启动微服务，然后输入微服务的IP+端口+/swagger-ui.html，就可以看到Swagger-UI了，如下：

通过Swagger-UI我们就可以校验的方式测试接口了，同时因为接口字段都在UI有说明和暂时，并且是与实际代码完全一致的，所以在对接时基于这些接口定义进行对接就可以了！