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

图像在API文档中扮演着重要角色，它们不仅能够提升文档的视觉吸引力，还能帮助用户更直观地理解复杂的技术概念。Bump.sh 一直支持在 API 文档中通过 Markdown 添加图像的功能，现在更进一步，新增了图像尺寸调整功能，让您可以根据需求自定义图像的显示效果。

Bump.sh 默认图像渲染方式

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

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



- 如果图像嵌入在表格单元格中，图像大小会受到单元格限制。

- 如果图像位于段落中，则会使用默认的图像大小。



不过，现在您可以通过自定义设置来决定图像的具体尺寸。



---



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



Bump.sh 引入了一个名为 =dimension 的参数，用于扩展 Markdown 图像语法，允许您手动设置图像的宽度和高度。语法格式如下：

![Alt text](https://cdn.explinks.com/path/to/image.jpg "Image title" =dimension)

例如，若要显示一个宽 100 像素、高 50 像素的图像，可以这样写：

![Alt text](https://cdn.explinks.com/path/to/image.jpg "Image title" =100pxx50px)

### =dimension 参数的语法规则

- 格式：=[width][unit]x[height][unit]
- 参数说明：
  - width：图像宽度（可选）。
  - height：图像高度（可选）。
  - unit：单位（可选，默认单位为像素 px）。
- 如果未指定 width 或 height，另一个值将根据图像原始比例自动计算。

以下是一些示例，帮助您更好地理解如何使用 =dimension 参数：

1. 默认渲染方式：
![](https://i.imgur.com/cu8U4wq.png)

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

![](https://i.imgur.com/d6wu60d.png "Image title" =100pxx50px)

3. 仅指定宽度（100px）：

![](https://i.imgur.com/jExxH3b.png "Image title" =100)

4. 仅指定高度（50px）：



![](https://i.imgur.com/BSJfnXr.png "Image title" =x50)

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

![](https://i.imgur.com/vcyBg4g.png "Image title" =200cm)

### 注意事项



- 如果未指定单位，默认使用像素（px）。
- 支持所有 CSS 长度单位，例如 px、% 等。
- 请确保所使用的单位和属性能够被不同浏览器正确解析。

---

## 如何尝试自定义图像尺寸

您可以通过 Bump.sh 提供的预览工具快速查看 API 文档中图像的显示效果。以下是操作步骤：

1. 安装 Bump.sh CLI 工具：
   ```bash
   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