网站首页 > 技术文章 正文
1.前言
API接口文档(API Documentation)是一种技术文档,用于描述系统提供的接口信息,帮助开发者了解如何使用这些接口进行开发和维护。API接口文档通常由开发人员编写,并在项目开发过程中持续维护和更新。
API接口文档的主要内容
API接口文档通常包含以下关键部分:
- 概述
- API的基本信息和目的。
- 版本号和更新历史。
- 认证
- 如何获取和使用API密钥或令牌。
- 认证流程和安全要求。
- 端点(Endpoints)
- 接口地址和请求方法(如GET、POST、PUT、DELETE)。
- 请求参数
- 参数字段名、类型、是否必填等。
- 响应内容
- 返回数据格式和内容,包括成功和失败的情况。
- 错误代码
- 可能出现的错误代码及其含义。
- 示例
- 提供实际的请求和响应示例,帮助开发者理解接口的使用
API接口文档的重要性
API接口文档是开发过程中不可或缺的一部分,它不仅帮助开发者快速理解和使用接口,还能提高团队协作效率,降低开发成本,并确保系统的稳定性和可维护性。
API接口文档是描述系统接口信息的技术文件,为开发者提供了详细的使用指南,是开发和维护系统的重要工具。
我们在很多网站上都看到过系统API在线文档。文档中包含的输入参数、输出参数、还有部分参考示例代码的。对技术人员来说通过文档可以快速实现调用该接口的测试代码。不过实际工作中及时文档写的比较详细了。但是我们在实现它的时候估计也会花费一点时间。此外有的文档并不一定提供各种编程语言对应的api示例代码。有没有办法导入在线或者离线的接口文档,一下就实现各种编程语言实现好的接口代码呢?今天就给大家带来实现api接口文档生成代码的dify工作流。
我们看一下工作流整体情况:
上面的工作流有2个分支,一个是实现在线API文档,一个是用户上传已经有的离线版接口文档。(接口文档可以是PDF、word、markdown格式),用户通过上传接口文档后通过文档提取器或者jina AI 爬取在线文档,后面在发送给大语言模型,通过大模型转换输出接口文档对应的实现代码。下面给大家介绍下工作流是如何实现的。
2.工作流实现
我们这里创建一个工作流。
开始
开始节点中我们这里设置4个值。 第一个值是 file,主要是用户上传的离线API 接口文档。
第二个参数我们接受用户输入的URL 这里我们设定文本类型。
第三个参数主要接受用户输入的其他条件值,比如说 用户输入的 Authorization api 值,我们需要用户这个值后最后把它写带代码里面生成。避免生成的代码还需要修改等。这里我们设定段落,因为不确定用户输入哪些接口需要的特定的值。
第四值 我们做成下拉选项,让用户根据API 接口生成对应的编程语言。这里我设定curl 、python、Java、goland、nodejs等几个主流的编程语言。这个选项我们设定必填项。
4个参考设定好后,开始节点内容如下:
条件分支
这里我们做一下条件分支判断,目的是区分用户输入的是离线版本接口文档还是在线版本的API在线文档。我们使用api-url不为空作为判断依据
以上代码实现起来不算严谨,感兴趣的小伙伴可以在我们上面的工作流上修改和完善。
jina AI获取单页面
这里我们需要一个jina AI的一个组件。这个组件主要的目的是用户输入的在线api 文档,这里我们使用302.AI 的官方在线文档接口—文/图生成视频
https://302ai.apifox.cn/api-256199633 案例讲解。
上面是一个标准的API 接口文档,我们需要利用jina AI来实现在线APi文档的抓取。
这里我们简单介绍一下这个Jina Reader
jina-ai可以将网页转出markdown格式的文件,公司官方网https://jina.ai/reader/
jina-ai 使用
使用方法
1.访问网站https://jina.ai/reader/
我们在左边输入需要抓取的URL链接,然后点击下面获取内容按钮,点击后右边就会把网页内容转换成markdown格式
- 使用api 接口方式
以上是在jina-ai网站上实现网页爬取。我们这里用到了dify工作流里面 jina-ai 内置组件来实现。
使用之前我们需要对这个组件授权添加apikey
授权完成后,就变成可用状态
有的小伙伴可能会问,这个APIkey 在哪里获取,要钱吗?
我们可以在 https://jina.ai/reader/ 网站上获取。目前这个api 送50万个(我测试使用基本上是够用的)
以上是关于jina-ai方面的知识,我们回到dify工作流中添加一个获取单页面的jina-ai ,如下图。
输入变量这里,我们主要是接受开始节点api_url,这个其实很好理解输入用户输入的网站地址信息让 jina-ai来爬取当前单个页面信息
文档提取器
这个文档提取器在这里和上面jina AI 是一个并行关系,主要的目的是解析用户输入的离线的API 接口文档。这个组件用的比较多,我们这里就不做详细展开。
变量聚合器
这个变量聚合器,我们在之前文章中《dify案例分享-基于多模态模型的发票识别2-多种发票识别》使用过。这里我们就不做详细展开。
主要目的是把文档提取器和网页获取的信息合并。本质上2个返回的结果都是接口文档内容信息。
llm大语言模型
这里我们使用llm大语言模型实现api 接口文档转换成代码实现文本生成。模型这块我们使用硅基流动提供的Qwen/QwQ-32B模型
系统提示词如下:
# 你是一个软件工程师,帮助用户解读API文档并直接生成代码。
## 工作流程
1. 根据用户的要求解读API文档
2. 简要想用户介绍API文档中涉及到的接口
3. 根据用户的要求使用{{#1740959153996.language#}}编写测试代码
## 工作要求
1. 如果在输入的接口文档找没有找到接口,请向用户澄清。
2. 如果输入的接口文档中找到了多个接口,请向用户澄清具体是哪个接口。
3. 如果文档中涉及到了api-key或认证相关内容,可以使用用户提供加入到接口中。
4. 如果文档中提及了某些必须传入的参数和认证用的api-key,而用户没有提供,请告知用户未生成代码的具体原因,并询问用户该如何处理必需的参数。如:按照API文档的描述,在调用XX接口时,需要提供XX参数,并询问用户该如何处理?
5. 请注意API文档中描述的输入和输出参数的格式,严格按照文档中描述的格式组织代码。
## 输出格式
1. 编写测试代码
2. 解释每个输入参数和输出参数具体的含义
这里我们还需要输入用户提示词。
接口文档内容如下{{#1740960349832.output#}}。
请使用 {{#1740959153996.language#}} 编写代码
用户要求:{{#1740959153996.other#}}
结束
后面的这个就是将大语言模型输出内容显示出来。
输出变量text 输出内容 text string
完成的工作流整体如下
3.验证及测试
因为流程中有2个测试点,离线文本接口和在线api接口。接下来我们分别测试一下。
3.1在线api接口
我们点击运行按钮,在API文档Ur 输入 api接口文档。这里我们以302.AI的一个文生视频文档接口为案例。
接口文档地址:
https://302ai.apifox.cn/api-256199633
额外说明: 我们填入接口需要的 Authorization Bearer xxx (方便生成的接口代码直接可以使用)
编程语言:选择python
点击开始运行按钮。
3.2 离线api接口
我们点击运行按钮,在API文档Ur 输入 api接口文档。这里我们以硅基流动I的一个文生图文档接口为案例。
接口文档地址:
https://mypicture-1258720957.cos.ap-nanjing.myqcloud.com/Obsidian/%E5%88%9B%E5%BB%BA%E5%9B%BE%E7%89%87%E7%94%9F%E6%88%90%E8%AF%B7%E6%B1%82%20-%20SiliconFlow.pdf
额外说明: 我们填入接口需要的 Authorization Bearer xxx (方便生成的接口代码直接可以使用)
编程语言:选择python
点击开始运行按钮。
以上工作流体验地址:
http://dify.duckcloud.fun/workflow/PV6F1n0URiKzNm0R
以上我们就完成了工作流的测试。
相关资料和文档可以看我开源的项目
https://github.com/wwwzhouhui/dify-for-dsl
4.总结
今天主要带大家实现了从 API 接口文档生成代码的功能。详细介绍了整个工作流的实现步骤,工作流包含两个分支,分别处理在线 API 文档和离线接口文档:
本次工作流整体有一难度不大,这里主要涉及到jina.ai工具的使用,前面关于这个工具的使用我也有介绍过。感兴趣的小伙伴可以动手尝试,今天的分享就到这里结束了,我们下一篇文章见。
猜你喜欢
- 2025-03-14 一个用 Rust 开发的极快、易用的 Python 包和项目管理利器
- 2025-03-14 python解释器管理工具pyenv使用说明
- 2025-03-14 Linux命令手册:从青铜到王者,这30个命令让你成为终端高手
- 2025-03-14 python爬虫混肴DES案例:某影视大数据平台
- 2025-03-14 AI应用下一个风口:知识库(ai智能应用)
- 2025-03-14 使用vllm部署自己的大模型(如何部署模型)
- 2025-03-14 Python调用OpenDaylight REST API实验
- 2025-03-14 Java教程:gitlab-使用入门(java gitbook)
- 2025-03-14 接入5家DeepSeek模型提供商!边缘大模型网关助力一键畅享大模型
- 2025-03-14 python爬虫如何一键构造请求(python 构造)
- 最近发表
- 标签列表
-
- cmd/c (57)
- c++中::是什么意思 (57)
- sqlset (59)
- ps可以打开pdf格式吗 (58)
- phprequire_once (61)
- localstorage.removeitem (74)
- routermode (59)
- vector线程安全吗 (70)
- & (66)
- java (73)
- org.redisson (64)
- log.warn (60)
- cannotinstantiatethetype (62)
- js数组插入 (83)
- resttemplateokhttp (59)
- gormwherein (64)
- linux删除一个文件夹 (65)
- mac安装java (72)
- reader.onload (61)
- outofmemoryerror是什么意思 (64)
- flask文件上传 (63)
- eacces (67)
- 查看mysql是否启动 (70)
- java是值传递还是引用传递 (58)
- 无效的列索引 (74)