1. MDN Web 文档
  2. 写作指南
  3. 操作指南
  4. 编写 API 参考

如何编写 API 参考

本指南将引导您了解在 MDN 上编写 API 参考所需的所有知识。

准备工作

在开始文档化 API 之前，您应该提前准备和计划一些事情，而不是等到真正开始编写时。

先决知识

假设您在阅读本指南之前对以下内容有相当的了解：

  • HTML、CSS 和 JavaScript 等 Web 技术。JavaScript 最为重要。
  • 阅读 Web 技术规范。在文档化 API 时，您会经常查阅这些规范。

其他一切都可以在实践中学习。

必备资源

在开始文档化 API 之前，您应该准备好以下资源：

  1. 最新规范：无论是 W3C 推荐规范还是早期编辑草案，您都应该参考涵盖该 API 的最新可用规范草案（或涵盖该 API 的多个规范）。通常可以通过 Web 搜索找到它。最新版本通常会从所有版本的规范中链接，列在“最新草案”或类似标题下。
  2. 最新的现代 Web 浏览器：这些应该是实验性/Alpha 版本，例如 Firefox Nightly/Chrome Canary，它们更有可能支持您正在文档化的功能。如果您正在文档化一个新兴/实验性 API，这一点尤其重要。
  3. 演示/博客文章/其他信息：尽可能多地查找信息。
  4. 有用的工程联系人：找到一个友好的工程联系人来询问有关规范的问题，或者参与 API 标准化或在浏览器中实现的人，这非常有帮助。找到他们的好地方是：
    • 如果您在相关公司工作，请查阅您的公司内部通讯录。
    • 参与该 API 讨论的公共邮件列表，例如 Mozilla 的 dev-platform 或 W3C 列表，例如 public-webapps。
    • 规范本身。例如，Web Audio API 规范在顶部列出了作者及其联系方式。

花些时间玩转 API

在文档化 API 的过程中，您会多次回来构建演示，但首先花时间熟悉 API 的工作原理很有用——了解主要的接口/属性/方法是什么，主要用例是什么，以及如何用它编写简单的功能。

当 API 发生变化时，您需要小心，确保您引用或学习的现有演示没有过时。检查演示中使用的主要构造，看它们是否与最新规范匹配。它们可能无法在最新浏览器中工作，但这不是一个非常可靠的测试，因为旧功能通常会为了向后兼容而继续受支持。

注意：如果规范最近更新，例如，一个方法现在以不同的方式定义，但旧方法仍然在浏览器中工作，您通常必须在同一位置文档化这两个方法，以便涵盖新旧方法。如果您需要帮助，请参考您找到的演示，或咨询工程联系人。

创建需要编写或更新的文档列表

API 参考通常包含以下页面。您可以在我们的页面类型文章中找到每个页面包含内容的更多详细信息、示例和模板。在开始之前，您应该写下所有需要创建的页面列表。

  1. 概述页
  2. 接口页
  3. 构造函数页
  4. 方法页
  5. 属性页
  6. 事件页
  7. 概念/指南页
  8. 示例

注意：本文将以 Web Audio API 为例。

概述页

单个 API 概述页用于描述 API 的作用、其顶层接口、其他接口中包含的相关功能以及其他高级细节。其名称和 slug 应为 API 名称加上“API”后缀。它放置在 API 参考的顶层，作为 https://mdn.org.cn/en-US/docs/Web/API 的子级。

示例

接口页

每个接口也将有自己的页面，描述接口的目的，列出其包含的任何成员（构造函数、方法、属性等），并显示其兼容的浏览器。页面的名称和 slug 应与规范中完全一致的接口名称相同。每个页面都放置在 API 参考的顶层，作为 https://mdn.org.cn/en-US/docs/Web/API 的子级。

示例

注意：我们文档化接口中出现的所有成员。您应该牢记以下规则：

  • 我们文档化在实现此接口的对象原型上定义的方法（实例方法）以及在类本身上定义的方法（静态方法）。在极少数情况下，它们同时存在于同一接口上时，您应该将它们列在页面上的不同部分（静态方法/实例方法）。通常只存在实例方法，在这种情况下，您可以将它们放在“方法”标题下。
  • 我们不文档化接口的继承属性和方法：它们列在各自的父接口上。但我们确实会提示它们的存在。
  • 我们确实文档化 mixin 中定义的属性和方法。有关更多详细信息，请参阅mixin 的贡献指南。
  • 如果存在，也会列出特殊的方言化器（toString()）和 JSON 化器（toJSON()）方法。
  • 如果相关，也会列出命名构造函数（例如 HTMLImageElement 的 Image()）。

构造函数页

每个接口有零个或一个构造函数，记录在接口页面的子页面上。它描述了构造函数的作用，并显示其语法外观、使用示例、浏览器兼容性信息等。其 slug 是构造函数的名称，与接口名称完全相同，标题是接口名称、点号、构造函数名称，然后是括号。

示例

属性页

每个接口有零个或多个属性，记录在接口页面的子页面上。每个页面描述了属性的作用，并显示其语法外观、使用示例、浏览器兼容性信息等。其 slug 是属性的名称，标题是接口名称、点号，然后是属性名称。

示例

方法页

每个接口有零个或多个方法，记录在接口页面的子页面上。每个页面描述了方法的作用，并显示其语法外观、使用示例、浏览器兼容性信息等。其 slug 是方法的名称，标题是接口名称、点号、方法名称，然后是括号。

示例

事件页

将事件文档化为其目标接口的子页面，并使用 slug eventname_event，标题设置为 Interface: eventName event。

不要为 on 事件处理程序属性创建页面。在 eventName_event 页面上同时提及访问事件的两种方式。

示例

概念/指南页

大多数 API 参考至少有一篇指南，有时还会附带一篇概念页面。最少，API 参考应包含一篇名为“使用 API 名称”的指南，它将提供如何使用 API 的基本指南。更复杂的 API 可能需要多篇使用指南来解释如何使用 API 的不同方面。

如果需要，您还可以包含一篇名为“API 名称概念”的概念文章，它将解释与 API 相关的任何概念的理论，开发人员应该理解这些概念才能有效地使用 API。

所有这些文章都应作为 API 概述页面的子页面创建。例如，Web Audio 有四篇指南和一篇概念文章：

示例

您应该创建一些示例，演示 API 最常见的用例。您可以将这些示例放在任何合适的地方，但建议放在 MDN GitHub 仓库。

列出所有这些

创建一个包含所有这些子页面的列表是跟踪它们的良好方式。例如：

  • Web_Audio_API

  • AudioContext

    • AudioContext.currentTime
    • AudioContext.destination
    • AudioContext.listener
    • …
    • AudioContext.createBuffer()
    • AudioContext.createBufferSource()
    • …

  • AudioNode

    • AudioNode.context
    • AudioNode.numberOfInputs
    • AudioNode.numberOfOutputs
    • …
    • AudioNode.connect(Param)
    • …

  • AudioParam

  • 事件（更新列表）

    • start
    • end
    • …

列表中每个接口都为其创建了一个单独的页面，作为 https://mdn.org.cn/en-US/docs/Web/API 的子页面；例如，AudioContext 的文档将位于 https://mdn.org.cn/en-US/docs/Web/API/AudioContext。每个接口页面都解释了该接口的功能，并提供了组成该接口的方法和属性列表。然后，每个方法和属性都在其自己的页面上进行文档化，该页面作为其所属接口的子页面创建。例如，BaseAudioContext/currentTime 文档位于 https://mdn.org.cn/en-US/docs/Web/API/AudioContext/currentTime。

创建页面

现在，根据以下结构创建您需要的页面。我们的 MDN 内容 README 包含创建新文档的说明，我们的 页面类型指南包含可能有用​​的更多示例和页面模板。

概述页面的结构

API 登陆页面的长度差异很大，具体取决于 API 的大小，但它们都将具有基本相同的功能。请参阅 https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API 以获取大型登陆页面的示例。

登陆页面的功能概述如下：

  1. 描述：登陆页面的第一段应提供 API 总体目的的简短、简洁描述。
  2. 概念和用法部分：下一部分应标题为“API 名称概念和用法”，并概述 API 提供的所有主要功能、它解决的问题以及它如何工作——所有这些都在高层次上。此部分应相当简短，不应涉及代码或具体的实现细节。
  3. 接口列表：此部分应标题为“[API 名称] 接口”，并提供指向构成 API 的每个接口的参考页面的链接，以及对每个接口功能的简短描述。请参阅“使用 {{domxref}} 宏引用其他 API 功能”部分，以更快地创建新页面。
  4. 示例：此部分应展示 API 的一个或两个用例。
  5. 规范表：此时您需要包含一个规范表——有关更多详细信息，请参阅“创建规范参考表”部分。
  6. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。
  7. 另请参阅：“另请参阅”部分是包含在学习此技术时可能有用​​的更多链接的好地方，包括 MDN（和外部）教程、示例、库等。

接口页面的结构

现在您应该准备好开始编写接口页面了。每个接口参考页面都应遵循以下结构：

  1. {{APIRef}}：在每个接口页面的第一行包含 {{APIRef}} 宏，并以 API 名称作为参数，例如 {{APIRef("Web Audio API")}}。此宏用于在接口页面的左侧构建一个参考菜单，包括属性和方法，以及 GroupData 宏中定义的其他快速链接（如果您的 API 尚未列出，请要求某人将其添加到现有 GroupData 条目中，或创建一个新条目）。菜单将如下图所示。此屏幕截图显示了 OscillatorNode 接口的垂直导航菜单，其中包含多个方法和属性子列表，由 APIRef 宏生成

  2. 功能状态：如果需要，将自动添加一个指示功能状态（例如已弃用、非标准或实验性）的横幅。为此，您需要更新 browser-compat-data 仓库中的状态。

  3. 描述：接口页面的第一段应提供对接口总体目的的简短简洁描述。如果需要任何其他描述，您可能还想包含几段。要包含的显而易见的额外信息是其默认/初始值，以及它是否是只读的。如果接口实际上是一个字典，您应该使用该术语而不是“接口”。

  4. 继承图：使用 {{InheritanceDiagram}} 宏嵌入接口的 SVG 继承图。

  5. 属性列表、方法列表：这些部分应标题为“属性”和“方法”，并提供指向（使用 {{domxref}} 宏）该接口的每个属性/方法的参考页面的链接，以及对每个属性/方法功能的描述。这些应使用描述/定义列表进行标记。每个描述都应简短简洁——如果可能，一句话即可。请参阅“使用 {{domxref}} 宏引用其他 API 功能”部分，以更快地创建指向其他页面的链接。

    在两个部分的开头，在属性/方法列表的开头之前，用斜体表示继承，使用适当的句子：

    • 此接口未实现任何特定属性，但继承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的属性。
    • 此接口也继承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的属性。
    • 此接口未实现任何特定方法，但继承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的方法。
    • 此接口也继承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的方法。

    注意： 只读属性应包含 {{ReadOnlyInline}} 宏，它会创建一个精美的“只读”徽章，包含在其 {{domxref}} 链接的同一行（在 {{experimental_inline}}、{{non-standard_Inline}} 和 {{deprecated_inline}} 宏之后，如果需要这些宏）。

  6. 示例：包含代码列表以展示 API 主要功能的典型用法。您不应该列出所有代码，而应该列出其有趣的部分。对于完整的代码列表，您可以引用包含完整示例的 GitHub 仓库，并且还可以链接到使用 GitHub gh-pages 功能创建的实时示例（只要它只使用客户端代码）。如果示例是可视化的，您还可以使用 MDN 实时示例功能使其在页面中实时可播放。

  7. 规范表：此时您需要包含一个规范表——有关更多详细信息，请参阅“创建规范参考表”部分。

  8. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。

  9. Polyfill：如果合适，请包含此部分，提供 polyfill 代码，即使在不支持 API 的浏览器上也能使用该 API。如果没有 polyfill 或不需要，则完全省略此部分。

  10. 另请参阅：“另请参阅”部分是包含在学习此技术时可能有用​​的更多链接的好地方，包括 MDN（和外部）教程、示例、库等。我们对链接到外部来源的政策很宽松，但请注意：

    • 不要包含与 MDN 中另一个页面信息相同的页面；请链接到该页面。
    • 不要列出作者姓名——我们是一个作者中立的文档网站。链接到文档；作者姓名将在那里显示。
    • 特别注意博客文章：它们往往会过时（旧语法、错误的兼容性信息）。仅当它们具有在维护的文档中找不到的明确附加价值时才链接到它们。
    • 不要使用“参阅……了解更多信息”或“点击……”等动作动词，您不知道您的读者是否能够看到或点击链接（例如在文档的纸质版本上）。

接口页面示例

以下是接口页面的示范性示例：

属性页面的结构

将您的属性页面创建为其所在接口的子页面。复制另一个属性页面的结构作为新页面的基础。

编辑属性页面名称以遵循 Interface.property_name 约定。

属性页面必须包含以下部分：

  1. 标题：页面的标题必须是 InterfaceName.propertyName。接口名称必须以大写字母开头。尽管接口在 JavaScript 中是在对象原型上实现的，但我们不在标题中包含 .prototype.，就像我们在 JavaScript 参考中那样。

  2. {{APIRef}}：在每个属性页面的第一行包含 {{APIRef}} 宏，并以 API 名称作为参数，例如 {{APIRef("Web Audio API")}}。此宏用于在接口页面的左侧构建一个参考菜单，包括属性和方法，以及 GroupData 宏中定义的其他快速链接（如果您的 API 尚未列出，请要求某人将其添加到现有 GroupData 条目中，或创建一个新条目）。菜单将如下图所示。此屏幕截图显示了 OscillatorNode 接口的垂直导航菜单，其中包含多个方法和属性子列表，由 APIRef 宏生成

  3. 功能状态：如果需要，将自动添加一个指示功能状态（例如已弃用、非标准或实验性）的横幅。为此，您需要更新 browser-compat-data 仓库中的状态。

  4. 描述：属性页面的第一段应提供属性总体目的的简短简洁描述。如果需要任何其他描述，您可能还想包含几段。要包含的显而易见的额外信息是其默认/初始值，以及它是否是只读的。第一句话的结构必须是：

    对于只读属性：

    InterfaceName.property 只读属性返回一个 {{domxref("type")}}，它……

    对于其他属性：

    InterfaceName.property 属性是一个 {{domxref("type")}}，它……

    注意： InterfaceName.property 应以 <code> 标签包裹，并且在第一次使用时还应加粗（<strong>）。

  5. 值：“值”部分将包含对属性值的描述。这应包含属性的数据类型及其所代表的含义。有关示例，请参阅 SpeechRecognition.grammars

  6. 示例：包含代码列表以展示所讨论属性的典型用法。您应该从一个简单的示例开始，展示如何创建该类型的对象以及如何访问该属性。在此类示例之后可以添加更复杂的示例。在这些附加示例中，您不应该列出所有代码，而应该列出其有趣的部分。对于完整的代码列表，您可以引用包含完整示例的 GitHub 仓库，并且还可以链接到使用 GitHub gh-pages 功能创建的实时示例（只要它只使用客户端代码）。如果示例是可视化的，您还可以使用 MDN 实时示例功能使其在页面中实时可播放。

  7. 规范表：此时您需要包含一个规范表——有关更多详细信息，请参阅“创建规范参考表”部分。

  8. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。

  9. 另请参阅：“另请参阅”部分是包含在使用此技术时可能有用​​的更多链接的好地方：例如受此属性更改影响的方法和属性，或与之相关的抛出事件。可以添加更多在学习此技术时有用的链接，包括 MDN（和外部）教程、示例、库等，尽管将其添加到接口参考页面可能更有用。

属性页面示例

以下是属性页面的示范性示例：

方法页面的结构

将您的方法页面创建为其所在接口的子页面。复制另一个方法页面的结构作为新页面的基础。

方法页面需要以下部分：

  1. 标题：页面的标题必须是 InterfaceName.method()（带两个末尾括号），但 slug（页面 URL 的末尾）不得包含括号。此外，接口名称必须以大写字母开头。尽管接口在 JavaScript 中是在对象原型上实现的，但我们不在标题中包含 .prototype.，就像我们在 JavaScript 参考中那样。

  2. {{APIRef}}：在每个方法页面的第一行包含 {{APIRef}} 宏，并以 API 名称作为参数，例如 {{APIRef("Web Audio API")}}。此宏用于在接口页面的左侧构建一个参考菜单，包括属性和方法，以及 GroupData 宏中定义的其他快速链接（如果您的 API 尚未列出，请要求某人将其添加到现有 GroupData 条目中，或创建一个新条目）。菜单将如下图所示。此屏幕截图显示了 OscillatorNode 接口的垂直导航菜单，其中包含多个方法和属性子列表，由 APIRef 宏生成

  3. 功能状态：如果需要，将自动添加一个指示功能状态（例如已弃用、非标准或实验性）的横幅。为此，您需要更新 browser-compat-data 仓库中的状态。

  4. 描述：方法页面的第一段应提供方法总体目的的简短简洁描述。如果需要任何其他描述，您可能还想包含几段。要包含的显而易见的额外信息是其默认参数值、方法所依赖的任何理论以及参数值的作用。

    第一句话的开头必须遵循以下结构：

    InterfaceName.method() 方法接口……

    注意： InterfaceName.method() 应以 <code> 标签包裹，并且在第一次使用时还应加粗（<strong>）。

  5. 语法：“语法”部分应包含 2-3 行示例——通常只是接口的构造，然后是接口方法的调用。

    语法应采用以下形式：

    method(param1, param2, …)

    “语法”部分应包含三个子部分（请参阅 SubtleCrypto.sign() 获取示例）：

    • “参数”：这应包含一个定义列表（或无序列表），其中命名并描述了方法接受的不同参数。对于可选参数，您应该在参数名称旁边包含 Optional 宏。如果没有参数，则应省略此部分。
    • “返回值”：这应说明该方法具有的返回值，无论是双精度浮点数或布尔值等简单值，还是像另一个接口对象这样更复杂的值，在这种情况下，您可以使用 {{domxref}} 宏链接到涵盖该接口的 MDN API 页面（如果存在）。方法可能不返回任何内容，在这种情况下，返回值应写为“{{jsxref('undefined')}}”（在渲染页面中将显示为：undefined）。
    • “异常”：这应该列出在调用方法时可能引发的不同异常以及导致它们的情况。如果没有异常，则应省略此部分。

  6. 示例：包含代码列表以展示所讨论方法的典型用法。您不应该列出所有代码，而应该列出其有趣的部分。对于完整的代码列表，您应该引用包含完整示例的 GitHub 仓库，并且还可以链接到使用 GitHub gh-pages 功能创建的实时示例（只要它只使用客户端代码）。如果示例是可视化的，您还可以使用 MDN 实时示例功能使其在页面中实时可播放。

  7. 规范表：此时您需要包含一个规范表——有关更多详细信息，请参阅“创建规范参考表”部分。

  8. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。

方法页面示例

以下是方法页面的示范性示例：

创建 API 参考页面后，您需要插入正确的侧边栏以将页面关联起来。我们的API 参考侧边栏指南解释了如何操作。

帮助改进 MDN

了解如何贡献

此页面由 MDN 贡献者 最后修改于 。

在 GitHub 上查看此页面 • 报告此内容的问题
© . Content available under a Creative Commons license.