微服务·API文档

阅文时长	| 3.92分钟	字数统计	| 2754.05字符
主要内容	| 1、什么是API文档 2、API文档的使用 3、声明与参考资料
『微服务·API文档』
编写人	| SCscHero	编写时间	| Thursday, December 3, 2020
文章类型	| 系列	完成度	| 待完善
座右铭	每一个伟大的事业，都有一个微不足道的开始。Hello World！

一、什么是API文档   完成度：100%

a) 广泛定义

由于在各个百科网站上没有给出准确定义，但不少大佬给了定义，以下是Keshav Vasudevan^[1]给出的定义。

1.API文档，它为什么重要?

我们处在一个多平台的经济环境中，而api是数字环境的粘合剂。平台是用户可以为其他用户扩展的产品。任何产品都可以通过为用户提供在其上添加服务和功能的方法成为平台。api是平台经济的推动者，允许用户在现有产品上增强和添加服务。当一个产品转变为一个平台时，它就有了一种新的用户类型:第三方开发人员。迎合开发商的需求是很棘手的。他们善于分析、精确，并试图解决API的重要问题。他们希望了解如何有效地使用API，这就是API文档的作用所在。

2.什么是API文档?

API文档是可交付的技术内容，包含关于如何有效地使用和集成API的说明。它是一个简明的参考手册，包含使用API所需的所有信息，以及关于函数、类、返回类型、参数等的详细信息，并支持教程和示例。API文档传统上是使用常规的内容创建和维护工具以及文本编辑器完成的。像OpenAPI/Swagger规范这样的API描述格式已经自动化了文档处理过程，使得团队更容易生成和维护文档。第三方开发人员是API的主要消费者，他们正忙于解决复杂的编程难题。对于技术用户来说，您的API是一种达到目的的手段，他们希望尽可能快地集成以推进软件开发，这意味着他们应该立即了解您的API的价值和用途。开发人员在发现、学习使用以及最终与API集成时积累的经验称为开发人员体验(DX^[2])。API文档是一个高评级DX的关键。

3. 为什么使用API文档？

在API生命周期的所有阶段中，文档可能是增长最快的领域。对于围绕文档的工具生态系统来说，这一点尤其正确。注意到这种趋势很有趣，因为文档通常是开发人员在启动代码时很少关注的东西。事实上，实现代码要比编写好的文档容易得多。但这是因为它对采用和使用的直接影响。你可以拥有最好的，功能性的产品，但如果不知道如何使用，没有人会去使用它。文档是良好开发人员体验的基础。

----来自《Swagger官网》^[3]

b) 个人理解

我对API文档理解是一个交付性成果，主要应用于前后端分离开发或者第三方API调用，并能增强API可维护性及可用性。在早前项目中（大概是2019年下半年），我们的项目就应用了Swagger，那时候只是简单使用，生成API文档，并苛求了自己写注释的习惯。对于其他功能，比如：API分组、自定义参数、Swagger导入Postman、分布式系统中网关集成文档，没有深入学习。因此，有了这篇博客总结沉淀一下。

二、API文档的使用   完成度：100%

a) 微服务下的API文档

单体架构下的API文档自然不必多说。但在分布式系统下的API文档，是否有所不同呢。此时我们需要了解微服务架构中的一个组件--API网关。我们需要将不同服务的API文档自动整合到一个项目中，这个项目可以是API网关，也可以是一个独立API文档管理系统（由任务调度器自动获取下游API数据，更新此系统）。

---

作为.Neter，博主会写一篇关于".NetCore3.1框架集成Ocelot+Swagger组件"的博客。

b) 常用的API文档组件

1. Swagger：开源；易上手；轻量级；RESTful风格；嵌入项目自动生成；UI简洁漂亮；不能保存参数；支持数据导出；适合前后端分离开发人员使用。
2. YApi：开源；权限管理；支持Swagger、Postman等数据导入；已有大企业使用中；维护麻烦（但有解决方案）；适合大规模团队使用。
3. Postman：保存在Collection的API集合可生成API文档。可以更改此文档为开放文档或私有账号文档；功能有局限性；但可保存参数；适合测试人员使用。

总结：博主用过Swagger和Postman的API文档。觉得两者结合使用可以满足大部分需求。YApi体验过，感觉还可以，权限功能比较实用，也因此受到了大企业的青睐。

三、声明与参考资料   完成度：100%

原创博文，未经许可请勿转载。

如有帮助，欢迎点赞、收藏、关注。如有问题，请评论留言！如需与博主联系的，直接博客私信SCscHero即可。

---

1. Keshav是技术领域公认的产品和市场领导者，对建立和发展基于SaaS的网络和移动应用程序充满热情。主导SmartBear软件两款成功SaaS产品的产品管理。帮助SwaggerHub的产品线增长了200%，并将其打造成了数百万美元的资产。专业领域包括产品管理、市场营销和数据分析，并倾向于将产品从测试版增长到规模化。有扎实的定量研究背景，了解大型复杂数据集的工作。获得 MEM 学位。技能：Adobe SiteCatalyst (Omniture)，Mixpanel, MS Office, XLMiner, Solver, HTML/CSS, JQuery, AJAX, Spotfire, JIRA, Adobe Photoshop, Swagger/OpenAPI规范，Ruby on Rails，谷歌分析，SEO优化，敏捷的产品管理。 ︎

2. DX是代表了API的理想开发体验的评级。数字越高，分数越高，10代表完美。该指数包括13个独立的标准，每个标准根据重要性进行加权。其中最重要的因素是:在主流语言中使用的库；深入浅出的入门指南；自助解决方案(不需要"演示"或"呼叫我们")；清晰的定价，让开发者知道它的成本； ︎

3. Swagger官方文档 ︎