文档API设计教程【免费下载链接】api-blueprintAPI Blueprint项目地址https://gitcode.com/gh_mirrors/ap/api-blueprint点击查看免费下载API Blueprint 是一套以 Markdown 为基础、面向文档的 Web API 描述语言本指南基于仓库中的官方文档 Glossary of Terms.md 编写系统梳理该语言体系中全部 23 个核心术语的定义与相互引用关系并结合 规范、基础教程、进阶教程 与 示例集 中的真实代码帮助你在阅读规范、编写.apib文档或使用解析器parser时准确理解每一个概念。读完本文你将能区分资源、动作、载荷、资产等易混术语并能在自己的蓝图中正确使用这些概念组织 API 描述。术语表的定位为什么先读它Glossary of Terms.md 是 API Blueprint 官方文档体系中的术语基准文件与 基础教程、进阶教程、语言规范 及 示例集 互为参照。仓库根目录的 README.md 在 Learn more 一节中专门列出了这份术语表Tutorial.md 也在开篇建议阅读教程过程中遇到概念不清楚时可随时查阅术语表。术语表本身通过定义 术语间互相引用的方式组织每个词条末尾都带有一个锚点如#def-action、#def-uri-template供规范与教程按名引用形成一张可追溯的概念网络。在深入语法之前先建立术语共识可以避免在学习 Resource资源、Action动作、Payload载荷等高频词时产生歧义。下面按概念层次分组讲解全部词条。顶层概念API、Blueprint 与 API BlueprintAPI定义API 即 HTTP 应用程序接口HTTP Application programming interface也可能指一份 API 描述description。在 API Blueprint 语境下API 通常有两层含义一是真实存在的 Web 服务接口本身二是对该接口的文字描述。当它指后者时即指向 API Blueprint 语言所书写的描述文档。Tutorial.md 的第一个步骤就是为你的 API 起名字并书写描述例如# Polls加上一句 Polls is a simple API allowing consumers to view polls and vote in them这里的 API 就是指被描述的对象。Blueprint定义一份API 描述。一个blueprint 文件或一组文件使用 API Blueprint 语言描述一个 API。Blueprint 是 API Blueprint 语言的产物形态。仓库中的 examples 目录 里每个.md文件都是一份独立可解析的 blueprint例如最简形式 examples/01. Simplest API.md 仅用五行代码就描述了一个GET /message接口。术语表特意说明 blueprint 可以是一个文件或一组文件——这与规范中blueprint 可以整体或部分地描述一个 Web API的表述一致见 API Blueprint Specification.md 中 API Blueprint document 一节。API Blueprint定义API Blueprint 语言即在 blueprint 文件中描述 API 所使用的格式。规范 API Blueprint Specification.md 对这门语言给出了更精确的定性API Blueprint 是一种文档导向documentation-oriented的 Web API 描述语言本质上是在 Markdown 语法之上叠加的一组语义假设除常规 Markdown 外还遵循 GitHub Flavored MarkdownGFM语法。也就是说.apib文件本身就是合法的 Markdown 文档其额外语义来自规范定义的关键字与章节结构。README.md 还给出了这门语言的媒体类型text/vnd.apiblueprint这也是各类工具识别蓝图文件的标准方式。HTTP 事务与消息模型这一组术语描述一次 HTTP 通信的静态结构是 Action 与 Payload 的基础。Method定义HTTP 请求方法HTTP Request Method。在 API Blueprint 中Method 是 Action 的标识要素之一。规范 API Blueprint Specification.md 的Keywords一节将 HTTP 方法如GET、POST、PUT、DELETE列为保留的 header 关键字与 URI 模板 组合即可定义动作如GET /resource/{id}。examples/03. Named Resource and Actions.md 展示了同一资源下[GET]、[PUT]两个方法各自定义动作的写法。注意除 HTTP 方法关键字外其余章节关键字大小写不敏感。Message定义一条HTTP 事务消息HTTP transaction message。Message 是对 HTTP 请求或响应消息的统称。在 API Blueprint 中一次 Action 就是一次请求-响应事务其两侧分别承载 Request 消息与 Response 消息消息由 消息头 与 消息体 构成。Message Header定义代表HTTP 事务消息头的一个 资产asset。消息头在蓝图中通常写为键值对形式。例如 examples/11. Resource Model.md 中的 Headers章节 Headers Location: http://api.acme.com/messageexamples/05. Responses.md 等响应示例中同样大量使用 Headers 描述响应头。教程 Tutorial.md 还指出一个便利特性在 Response 200 (application/json)中指定媒体类型会自动生成Content-Type消息头无需再手工书写。Message Body定义代表HTTP 事务消息体的一个 资产asset。消息体通常以 Markdown 缩进代码块pre-formatted code block书写。例如 examples/01. Simplest API.md 中的响应体 Response 200 (text/plain) Hello World!Asset定义原子数据atomic data。通常表示一个资源表示resource representation其形式为消息体或其验证 schema。Asset 是术语表中承上启下的抽象概念Message Body、Message Header、Schema 都是一个 asset。规范 API Blueprint Specification.md 中定义的Asset section是抽象章节其内容必须是预格式化代码块如 JSON 示例或 schema不能直接使用只能被其他具体章节继承——这与原子数据的定位完全吻合。Entity 与 Property定义Entity是在 载荷payload中被传输的实体Property是实体的一个字段属性。两者是同一事物的两面载荷里传输的是实体实体由若干属性构成。在 Tutorial.md 的 JSON 响应示例中一个 question 实体包含question、published_at、url、choices等属性choices数组中的每一项如{choice: Swift, url: ..., votes: 2048}又是嵌套的子实体。理解这一对概念有助于后续区分 AttributeMSON 层面的属性描述与 Property实体结构层面的字段。Payload、Request 与 ResponsePayload定义一条HTTP 事务消息连同其讨论文字以及任何附加的 资产如实体体的验证 schema。Payload 是术语表中最重要的复合概念之一其要点有二组成消息本身 描述文字 附加资产典型如 JSON Schema标识符identifier请求型载荷以字符串为标识符响应型载荷以HTTP 状态码为标识符。例如 examples/11. Resource Model.md 中 Request Update Plain Text Message (text/plain)的标识符是字符串 Update Plain Text Message而 Response 204的标识符则是状态码204。教程 Tutorial.md 专门举例说明无消息体的响应 Response 204只需状态码无需任何资产。Request定义包含一个特定 HTTP 请求的 载荷。Request 章节在 Action 内定义描述调用该动作时需要发送的请求。可选的组成部件包括 Headers、Attributes、Body 与 Schema。教程 Tutorial.md 中的创建问题请求示例 Request (application/json) { question: Favourite programming language?, choices: [ Swift, Python, Objective-C, Ruby ] }examples/06. Requests.md 提供了更多请求写法。Response定义包含一个特定 HTTP 响应的 载荷。Response 是 Action 的必备部件——规范中的文档结构明确规定每个 Action 必须包含1个 Response 章节见 API Blueprint Specification.md 的Blueprint document structure。响应以状态码为标识符可选的组成部件与 Request 相同。examples/05. Responses.md 系列示例演示了从纯文本到 JSON 的各种响应写法examples/01. Simplest API.md 则是最简响应的典范 Response 200 (text/plain)加一个消息体。资源建模Resource、Resource Set 与 Resource ModelResource定义由URI指定的 API资源也可以指匹配同一 URI 模板 的一组资源。资源是 API Blueprint 文档结构的核心单元。规范文档结构见 API Blueprint Specification.md中0个 Resource 章节可直接出现也可嵌套在0个 Resource Group 章节之下。资源的典型写法是标题 方括号内的 URI如 examples/03. Named Resource and Actions.md# My Message [/message]教程 Tutorial.md 中## Question Collection [/questions]也是同一模式。资源下可嵌套 URI Parameters、Attributes、Model 与若干 Action。Resource Set定义一组 API资源其URI匹配一个特定 URI 模板。当一个资源的 URI 包含模板变量如/questions/{question_id}它就描述了一整组同构资源即一个资源集。这个概念解释了为何一个资源可以匹配一个 URI 模板——模板变量的每一次取值都对应集合中的一个具体资源。Tutorial.md 中的## Question [/questions/{question_id}]正是资源集的典型例子。Resource Model定义一个资源在载荷形式下的表现manifestation即该资源的示例表示之后可以在需要 载荷 的位置被引用。Resource Model 是 API Blueprint 的复用利器examples/11. Resource Model.md 先在资源下定义 Model (application/vnd.sirenjson)包含 Headers 与 Body Model (application/vnd.sirenjson) 这是 application/vnd.sirenjson 消息资源的表示。 Headers Location: http://api.acme.com/message Body { class: [ message ], properties: { message: Hello World! }, links: [ { rel: self , href: /message } ] }随后在 Response 200中通过[My Message][]直接引用该模型避免了重复维护相同响应体。规范文档结构显示Model 章节位于资源下可包含0-1个 Headers、Attributes、Body 与 Schema 子章节——与载荷结构完全一致这正是模型即载荷的设计依据。URI 模板、参数与动作URI Template定义通过变量展开描述一系列URI的紧凑字符序列。URI Template 是资源寻址的基础。教程 Tutorial.md 用/questions/{question_id}说明了模板变量的写法变量以花括号包围。在 API Blueprint 中 URI 模板出现在两个位置资源标题的方括号内如/questions/{question_id}以及动作标题中与方法组合如GET /questions/{question_id}。规范 API Blueprint Specification.md 将其列为保留的 header 关键字并在附录III. Appendix 的 URI Templates 章节给出进一步的语法说明。Parameter定义一个 URI 模板变量。模板中的每个变量都需要用 Parameter 描述其类型、可选性与含义。教程 Tutorial.md 给出的写法 Parameters question_id (number) - ID of the Question in the form of an integer注意两种写法上的差别URI 模板中变量写作{question_id}而参数章节中写作question_id (number)并附加描述。规范文档结构规定URI Parameters 章节可出现在资源级0-1与动作级0-1资源级参数对所有动作生效动作级参数只对该动作生效。examples/10. Data Structures.md 展示了带默认值的可选参数 Default: 10等进阶用法。Action定义一次HTTP 事务请求-响应事务由 资源 内的 HTTP 请求方法 指定。Action 是资源的行为单元。规范文档结构规定每个资源必须包含1个 Action 章节每个 Action 可包含0-1个 Relation、URI Parameters、Attributes 章节0个 Request 章节与1个 Response 章节。动作的写法是动作名 方括号内的方法如 examples/03. Named Resource and Actions.md## Retrieve a Message [GET] Response 200 (text/plain) Hello World!Tutorial.md 强调每个动作至少需要一个响应响应必须包含状态码、可包含消息体。命名清晰的动词短语Retrieve a Message、Create a New Question是最佳实践。Trait定义API Blueprint章节SECTION的一种品质或特征quality or characteristic。Trait 描述的是章节层面的抽象特性而非具体内容。规范中章节可以定义其名称identifier、描述、嵌套章节或特定格式的内容Trait 即用于归纳这些可被识别的共性特征例如这是一个命名章节这是一个资产章节等抽象属性。理解 Trait 有助于把握规范中抽象章节不能直接使用、只能被具体章节继承的设计思想。数据结构Attribute、Data Structure 与 SchemaAttribute定义根据上下文指消息体数据结构的属性property、资源的属性或一次转换transition即 Action的输入属性。Attribute 是一个按上下文变化的多义词对应规范中Attributes 章节可出现在资源级、Model 级、Action 级以及 Request/Response 级的多重位置文档结构中的0-1Attributes。属性的写法使用 MSON 语法Markdown Syntax for Object Notation例如 Tutorial.md 创建问题动作中的 question (string) - The question choices (array[string]) - A collection of choices.examples/09. Advanced Attributes.md 与 examples/08. Attributes.md 提供了由浅入深的属性描述示例。当蓝图中写了 Attributes 时解析器会据此自动生成对应的 JSON 消息体与 JSON Schema详见 Advanced Tutorial.md 的 Attributes 一节。Data Structure定义一种特定的数据组织方式或其描述。在 API Blueprint 中数据结构及其 属性 使用MSON描述。Data Structure 是属性复用的容器。规范文档结构规定0个 Data Structures 章节位于文档末尾examples/10. Data Structures.md 展示了经典用法把多个属性描述共享的部分抽取为Coupon Base结构再让Coupon与Create a Coupon动作的 Attributes 以(Coupon Base)为基类型引用# Data Structures ## Coupon Base (object) percent_off: 25 (number) 一个 1 到 100 之间的正整数表示优惠券将应用的折扣。 redeem_by (number) - 优惠券可兑换的截止日期进阶教程 Advanced Tutorial.md 的 Data Structures 一节演示了(array[Question])、(array[Choice])这类引用方式让响应属性直接复用已定义的结构。Schema定义以 资产 形式存在的验证 schema用于验证或描述一个 消息体。Schema 是对消息体结构的精确约束。进阶教程 Advanced Tutorial.md 的 JSON Schema 一节给出了完整示例在 Schema下列出 JSON Schema$schema、type、properties、required、minItems等例如 Schema { $schema: http://json-schema.org/draft-04/schema#, type: object, properties: { question: { type: string }, choices: { type: array, items: { type: string }, minItems: 2 } } }examples/14. JSON Schema.md 与 examples/15. Advanced JSON Schema.md 提供更多实战样例。注意进阶教程中的提醒由 Attributes 自动生成的 Schema 可能比手写 Schema 宽松例如不包含minItems若有此类约束可手写 Schema 覆盖此时仅 JSON 消息体仍由 Attributes 生成。术语速查表术语一句话定义典型出处APIHTTP 应用程序接口或对它的描述Tutorial.mdBlueprint一份 API 描述一个或一组文件examplesAPI Blueprint描述 API 的语言/格式媒体类型text/vnd.apiblueprintREADME.mdAction一次 HTTP 请求-响应事务examples/03. Named Resource and Actions.mdMethodHTTP 请求方法GET、POST 等API Blueprint Specification.mdMessage一条 HTTP 事务消息—Message Header表示消息头的资产examples/11. Resource Model.mdMessage Body表示消息体的资产examples/01. Simplest API.mdAsset原子数据消息体、消息头、schema 的抽象基类API Blueprint Specification.mdEntity / Property载荷中传输的实体 / 实体的字段Tutorial.mdPayload消息 讨论 附加资产的复合体以字符串或状态码为标识符examples/11. Resource Model.mdRequest / Response含单个 HTTP 请求 / 响应的载荷examples/06. Requests.md、examples/05. Responses.mdResource由 URI 指定的资源可匹配一个 URI 模板examples/03. Named Resource and Actions.mdResource SetURI 匹配同一 URI 模板的一组资源Tutorial.mdResource Model资源的示例载荷表示可被请求/响应引用examples/11. Resource Model.mdURI Template通过变量展开描述 URI 范围的紧凑序列Tutorial.mdParameterURI 模板变量Tutorial.mdAttribute消息体属性 / 资源属性 / 动作输入属性MSONAdvanced Tutorial.mdData Structure用 MSON 描述的数据组织方式examples/10. Data Structures.mdSchema验证消息体的资产如 JSON SchemaAdvanced Tutorial.mdTraitAPI Blueprint 章节的品质或特征API Blueprint Specification.md结语把术语放进文档结构中掌握这些术语后一条贯穿全表的线索就很清晰了Blueprint 由章节SECTION构成章节围绕 Resource 组织每个 Resource 由 URI可能含 Template寻址其行为由 Action 承载每个 Action 至少含一个 Response 载荷载荷由消息、资产与标识符组成数据形态则由 Attribute、Data Structure 与 Schema 描述。规范的 Blueprint document structure 一节给出了这些术语在文档中的精确位置与数量约束如1个 Response、0-1个 Attributes是验证理解的最佳对照物。若需进一步巩固推荐按以下顺序继续阅读本仓库Tutorial.md——从零编写一个完整 API 蓝图的入门实操Advanced Tutorial.md——JSON Schema、MSON Attributes、Data Structures 与 Relation 的进阶用法API Blueprint Specification.md——每个术语对应的完整章节语法定义examples 目录——从最简 API 到超媒体 API 的 15 个可解析示例含 Gist Fox API.md、Real World API.md 等大型实例。赞分享文档API设计教程【免费下载链接】api-blueprintAPI Blueprint项目地址https://gitcode.com/gh_mirrors/ap/api-blueprint点击查看免费下载相关推荐OpenTofu 术语与核心概念指南从 Attribute、Resource 到 HCL 求值语义OpenTofu 术语与核心概念指南从 Attribute、Resource 到 HCL 求值语义 导读 本文是 OpenTofu 官方术语表 docs/g云原生DevOps基础设施scikit-learn 术语与 API 约定完全指南读懂 Glossary 中的每一个核心概念scikit learn 术语与 API 约定完全指南读懂 Glossary 中的每一个核心概念 本篇指南以 doc/glossary.rst https:/人工智能机器学习数据科学Spack 术语全景指南一文读懂 Spec、DAG、Concretization 与全部核心概念Spack 术语全景指南一文读懂 Spec、DAG、Concretization 与全部核心概念 导读本指南以 Spack 官方文档 glossary.rs开发工具构建工具CLI上一篇laf平台终极DDoS防护实践指南从流量清洗到弹性扩容的完整解决方案下一篇DANet与主流分割模型对比PSPNet、DeepLab、FCN全面评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考