Bump.sh 教你在 API 文档中精确调整图像尺寸

一. 图像在 API 文档中的重要性

在 API 文档中，图像不仅提升视觉吸引力，还能帮助用户更直观地理解复杂技术概念。Bump.sh 支持在 Markdown 中添加图像，并新增了图像尺寸调整功能，让文档作者可以根据需求自定义图像显示效果，从而提高文档的可读性和专业度。

二. Bump.sh 默认图像渲染方式

在 Markdown 中，您可以通过以下语法添加图像：

![描述文本](image-url)

默认情况下，Bump.sh 会让浏览器决定图像的显示方式：

• 当图像嵌入表格单元格时，大小受单元格限制。
• 当图像位于段落中时，使用默认图像尺寸。

现在，您可以通过自定义设置，精确控制图像的宽度和高度。

三. 如何在 API 文档中自定义图像大小

Bump.sh 引入了 =dimension 参数，用于扩展 Markdown 图像语法，允许手动设置图像宽度和高度。

1. =dimension 参数语法规则

• 格式：=[width][unit]x[height][unit]

• 参数说明：

  • width：图像宽度（可选）
  • height：图像高度（可选）
  • unit：单位（可选，默认单位为像素 px）
• 如果未指定 width 或 height，另一个值将根据图像原始比例自动计算

2. 示例用法

a. 默认渲染方式

![示例图](image-url)

b. 指定宽度和高度（100px x 50px）

![示例图](image-url)=100x50

c. 仅指定宽度（100px）

![示例图](image-url)=100x

d. 仅指定高度（50px）

![示例图](image-url)=x50

e. 使用其他单位（例如厘米 cm）

![示例图](image-url)=5cmx2.5cm

3. 注意事项

• 未指定单位时，默认使用像素（px）
• 支持所有 CSS 长度单位，如 px、% 等
• 确保单位和属性可被不同浏览器正确解析

四. 如何尝试自定义图像尺寸

使用 Bump.sh 提供的预览工具，可快速查看 API 文档中图像的显示效果：

1. 安装 Bump.sh CLI 工具：

npm install -g bump-cli

2. 预览 API 文档：

bump preview --live --open openapi-definition.json

• 参数 --open：在默认浏览器中打开预览
• 参数 --live：实时更新预览，文件保存后自动刷新浏览器

通过这些步骤，您可以轻松调整图像尺寸并实时查看效果。

五. 总结

Bump.sh 的图像尺寸调整功能为 API 文档提供了更高的个性化和专业化呈现方式。无论是展示动态 GIF、复杂 API 图表，还是说明多态性等高级概念，都可以通过简单的 Markdown 扩展语法实现精确控制。尝试使用这一功能，让您的 API 文档更生动、直观！

原文链接: https://bump.sh/blog/sizing-image-api-documentation