在 API 开发、沟通与协作中,API 文档在逻辑上是标准做法,但在实际操作中,仍存在通过 Word 或 PDF 格式文件来回传递的问题。因此,推荐使用在线文档来提升团队之间的沟通效率。创建快速分享#
点击“New”创建一个新的快速分享。一个项目支持多个不同的快速分享,可分发给不同的协作者。每个团队成员都可以看到所有人创建的全部快速分享。标题:此分享的名称,仅在 Apidog 团队内可见,用于内部识别,不会显示在分享出去的文档中。
环境:选择在线文档中可用的环境。默认不选择任何环境。你可以选择多个环境。选中的环境会在文档中对阅读者可见,并且在使用“Try it out”时可用于发送请求。
如果在创建文档时选择 Cloud mock 环境,相当于为文档阅读者启用了一个简单的沙盒环境。
文档内容:文档有两个可选组件:Base URL 和请求示例。你可以选择是否在文档中显示它们。Base URL:这是在环境中设置的基础 URL。如果选中,文档中的每个接口都会显示完整 URL;如果未选中,文档中的 URL 将以“/”开头。
请求示例:是否显示调用请求的示例代码。详情请参见请求示例。 允许导出数据:是否允许阅读者以 OAS/Markdown/HTML/Apidog 格式导出数据。
分享范围:选择此分享中要包含哪些 API 端点和 Markdown。你可以按目录选择,或按标签筛选和排除。
安全:你可以设置访问此文档是否需要密码,以及此文档的过期时间。如果未选择过期时间,则永不过期。
显示 API 字段:你可以设置这些字段是否显示在文档中。包括:负责人、更新时间、OperationId、原始链接、需要授权。
语言:这里的语言设置会影响文档中的功能性固定文本,例如“Query Params”“Request samples”等,但不会影响 API 文档内容中编写的文本。
高级设置:你可以在此设置隐藏“Try it out”按钮和隐藏“Powered by Apidog”。
分享整个文件夹#
快速分享支持“分享整个文件夹”。这适用于以下场景:分享链接后,你可能在文件夹中新增或删除了文档,并希望协作者能够同步看到这些变更。在“分享范围”中,当你选择“手动选择”时,可以看到“分享整个文件夹”。如果启用,协作者将始终看到该文件夹中的所有文档,而无需你在新增文档后手动修改分享范围。请求示例#
你可以在创建分享时选择是否显示此模块。
你可以自定义请求示例。操作方法如下:1.
在项目设置 - 功能设置 - 端点功能设置 - 端点字段中,启用请求示例字段。
2.
然后在端点 - 编辑中,末尾会出现一个请求示例模块。
3.
你可以点击此处的添加请求示例,添加所需语言的示例。随后它会显示在文档中。
分享链接#