据了解，在
导读
微服务架构下，软件系统分为几个独立运行的服务。 这些服务之间需要进行交互通信，并且需要定义各种服务接口。 具体来说，在基于Spring Cloud的微服务模型中，每个微服务基于Spring MVC的控制器定义了多个该微服务必须向外部公开的接口。根据各微服务功能的边界定义，一些微服务提供与特定业务相关的接口，如支付接口账户接口等； 有些微服务提供公共服务接口，如消息传递接口集成验证接口。 这些微服务经常由多个不同的团队开发和维护。 在传统方法中，服务接口的定义需要提供一个相对易读的接口文档，以便服务提供商可以更容易地对接和测试。 事实上，由于工作人员会随着时间的推移而更新，因此这些早期的界面文档往往很快就不再维护。 但是，在微服务模式下，这种方法会导致服务接口文档太多，这让开发人员很烦躁。
那么，是否有更方便的方法来在开发接口的同时自动生成与服务接口高度匹配的文档呢？ 有答案。 接下来，我们来和大家谈谈有什么样的方法来简化微服务的接口管理吧。
接口管理方式介绍
实际上，市场上已经有很多开源项目提供了这样的支持！ 例如，swaggerapidocrapdoclevercrapapi等所有这些项目都提供了Api在线文档的管理功能，但是在Spring Cloud体系中，哪种方法更合适呢？ 现在，让我们来比较一下这些项目的优缺点。1 .斯瓦格
Swagger是基于YAMLJSON语言的文档在线生成和代码自动生成的工具。 其优点如下
可以直接嵌入到Spring Boot项目中，通过在开发时进行注释，自动生成接口文档，实现代码与文档的高度匹配，分析了接口的结构， 可以通过发出请求来验证接口的正确性。提供基于定义的接口支持导出不同语言的服务器端或客户端代码的多种编程语言的前后分离解决方案。 它还包括一个使用yaml语言的Swagger API的编辑器——swagger编辑器——支持导出yaml和json格式的接口文件。 包含Swagger UI，可以将在Swagger UI编辑器中编辑的界面文档显示为html。 免费开源、支持国际化、生态丰富的社区活跃的缺点包括
代码具有侵入性的不同项目的Swagger接口文档是分离的，需要去不同的地方Swagger UI展示的接口文档缺乏分类，使用起来不舒服； 不同项目的接口文档没有权限管理，缺少Mock； 2. ApiDoc
ApiDoc是一种轻量级的在线文档生成工具，如Swagger。 缺点也和Swagger类似，界面管理自动测试等功能也很弱，在社区生态国际化方面也不如Swagger。
3. RAP
RAP是可视化接口管理工具，可以分析接口结构，动态生成仿真数据，验证实际接口的正确性，以接口定义为中心，通过一系列自动化工具提高微服务模式下的协作效率
其优点如下
支持Mock测试数据，支持项目管理团队对文档进行版本控制； 阿里大厂的产品在阿里巴巴内部实践； 分析接口检索的支持接口结构，可以启动请求验证接口的正确性； 开源的缺点包括：
文档和接口分离，容易发生不一致的每个接口都需要手动编辑； 后端由nodejs编写，与基于Java的Spring Cloud技术堆栈不匹配； 4.do清除程序
DOCLever也是一种免费的开源界面管理工具，其优点包括：
支持项目管理团队的文档管理工具丰富，支持Mock测试数据丰富的用户案例也丰富。 滴滴美团58同城同城旅行等； 分析接口检索支持接口的结构，检查接口正确性的参数也很丰富； 支持复杂场景的自动化测试，如获取授权码登录、获取订单列表和特定订单的详细信息，其缺点包括：
文档和接口分离，容易发生不一致的每个接口都需要手动编辑； 后端也是用nodejs写的，和Spring Cloud的Java技术栈不一致5. CrapApi
好处包括：
支持Mock测试数据，支持项目管理团队对文档进行版本控制； 可以分析接口检索支持接口结构的启动请求，验证接口的正确性； 基于后端Java开发，支持接口监控，设置报警规则，在接口不可用时及时通知服务主管，并与Spring Cloud技术堆栈Java一致； 缺点：
文档和接口分离，容易发生不一致的每个接口都需要手动编辑； 使用案例少，功能不充分，可能有很多漏洞； 6 .弹簧云集成s
wagger通过对上述开源项目的分析，除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有说明和暂时，并且是与实际代码完全一致的，所以在对接时基于这些接口定义进行对接就可以了！
Java架构师丨义气的魔镜：专注于Java开发技术的研究与知识分享！
————END————
点赞（感谢）...转发（感谢）...关注（感谢）...