助力集成开发，一文解锁API文档功能
在IT集成项目中，除了具备优质的API文档，我们还常常需要分享这些文档给外部开发人员或其他相关方，这对于项目团队的顺畅协作相当重要。
然而，面对以下API文档协作的场景，我们应该怎么处理呢？
部分人员无法访问苍穹系统（如对方系统开发），如何确保他们能够轻松查阅API文档？
没有网络连接时，我们又该如何随时查看离线API文档呢？
我们的API文档是否支持广泛使用的Swagger文档规范？
今天小编为你揭晓答案~详细聊聊苍穹开放平台中多样的API文档样式及应用指南！
适用版本
该功能适用版本为苍穹V5.0.021及以上
功能速览
为了帮助开发人员快速进行API接口调用，【开放平台】提供了“API文档”功能，当用户新建API服务并保存发布后，接口文档会自动展示在API文档中，左树按云-应用-业务对象分类。文档包含API基本信息，请求参数、返回参数、请求结构示例、返回结构示例和错误码信息。
图1 开放平台API文档
“API文档”提供了三种文档样式（在线HTML、线下PDF、Swagger），让开发者在不同场景下均能快速获取并分享API文档。具体教程如下：
1、导出在线HTML文档
路径：【开发服务云】→【开放平台】→【API文档】
当有外部系统用户需要查看API文档，但没有金蝶云苍穹账号时，我们可以点击右上角的“获取链接”按钮，会自动生成一个匿名访问的API清单链接网址，外部系统用户无需登录系统，即可查看API文档。
2、导出PDF文档
路径：【开发服务云】→【开放平台】→【API管理】→【API开发】
进入API管理列表，勾选需要导出的API，点击“导出PDF”按钮，系统自动生成离线API文档。
图3 开放平台API导出PDF
PDF文档效果如下，同样包含API基本信息、请求参数、返回参等信息。
图4 API离线PDF文档
3、导出Swagger
为提供更友好的统一交互体验，在新版本（V5.0.021）中，开放平台还支持导出Swagger样式的文档。Swagger是一种广泛使用的API文档规范，它具有清晰的结构和交互式的界面，帮助开发人员更直观地了解和调试API。
操作路径同上，进入API管理列表，勾选需要导出的API，点击“导出swagger”按钮，生成json文件，内容为Swagger3.0标准格式。
图5 开放平台API导出swagger
文件打开如下图所示，将内容复制到Swagger 编辑器（https://editor.swagger.io/#/），接口文档结构清晰，开发人员可快速了解接口并进行调试。
图6 导出swagger生成json文件
图7 Swagger样式的API文档
亮点价值
1、多格式文档导出
API文档功能支持导出在线链接HTML、线下PDF文档和Swagger样式的文档，为用户提供了全方位的文档导出选择，提高工作效率和灵活性。
2、提升开发效率和易用性
通过提供Swagger样式的文档，我们的产品进一步提升了API文档功能的易用性和开发效率。开发人员可以更快速地理解和集成API，减少错误并缩短调试时间，降低交付成本。
划重点
1、开放平台OpenAPI支持导出多种类型的API文档（HTML、PDF、Swagger），帮助开发人员快速进行集成对接。
2、在新版本（V5.0.021）中，产品支持导出Swagger样式的API文档，提供一致的标准化文档格式和更友好的交互体验。
#往期推荐#
助力集成开发，一文解锁API文档功能
本文2024-09-23 00:26:58发表“云苍穹知识”栏目。
本文链接：https://wenku.my7c.com/article/kingdee-cangqiong-139534.html
