如何在AWS API开发者门户展示完整的API介绍内容？

关于完整展示API介绍的可能性 #

目前AWS API Gateway的Developer Portal在渲染API级别的info.description字段时，存在仅解析并显示第一行文本的限制——不管是导入带Markdown格式的Swagger文件，还是手动在控制台编辑文档，多行内容都会被截断。甚至使用AWS官方文档提供的示例JSON测试，也会出现同样的问题。这是当前服务的已知局限性，暂时没有直接配置项能让Developer Portal完整渲染多行Markdown格式的API介绍。

替代方案：添加外部文档链接 #

如果无法在Developer Portal直接展示完整介绍，可以通过以下方式引导用户访问外部完整文档：

• 利用OpenAPI规范字段：在Swagger/OpenAPI定义的info.contact中补充文档链接，或者使用扩展字段x-externalDocs（符合OpenAPI标准），示例如下：

{
  "info": {
    "description": "API快速概览",
    "contact": {
      "name": "完整API文档",
      "url": "https://your-docs-domain.com/api-guide"
    },
    "x-externalDocs": {
      "description": "查看详细开发指南",
      "url": "https://your-docs-domain.com/api-guide"
    }
  }
}

Developer Portal会识别并展示contact中的链接，部分版本也支持x-externalDocs字段，用户可直接点击跳转至外部文档。

• 第一行文本嵌入链接：把API介绍的第一行设置为带链接的引导语，示例：

{
  "info": {
    "description": "点击查看[完整API开发者指南](https://your-docs-domain.com/api-guide)"
  }
}

虽然只能显示一行，但可以直接引导用户访问外部完整文档。

额外建议 #

如果AWS支持未及时回复，可尝试在AWS开发者论坛或GitHub上的AWS相关公开仓库提交反馈，推动该功能的优化迭代。

内容的提问来源于stack exchange，提问作者JukkaT