天道酬勤,学无止境

apiblueprint

尝试使用 API Blueprint 中的数据结构来描述请求和响应(Trying to describe the request and response using Data Structures in API Blueprint)

问题 我正在尝试使用规范的新 Attributes 和 DataStructures 部分来记录带有 API Blueprint 的端点。 我的请求负载如下所示: { "url": "http://requestb.in/11v7i7e1", "active": true, "types": [ { "name": "sales", "version": "2.0" }, { "name": "products", "version": "2.0" } ] } 我的响应负载看起来像这样: { "data": { "id": "dc85058a-a683-11e4-ef46-e9431a15be8c", "url": "http://requestb.in/11v7i7e1", "active": true, "types": [ { "name": "products", "version": "2.0" }, { "name": "sales", "version": "2.0" } ] } } 我尝试了以下 API 蓝图降价: FORMAT: 1A # Vend REST API 2.0 # Group Webhooks ## api/2.0/webhooks [/webhooks] ### List all Webhooks [GET] Returns a list of

2021-11-29 17:34:54    分类:技术分享    api   apiblueprint   apiary.io   apiary   MSON

API Blueprint 中的响应描述和 POST 参数(Response description and POST parameters in API Blueprint)

问题 我正在尝试 API Blueprint 并发现了一些我不太清楚的东西。 1. 如何记录 POST 正文参数? 有+ Parameters但它只记录查询参数。 如果我现在想描述一个 POST API,我无法记录 POST 参数(application/x-www-form-urlencoded)。 JSON 也是如此(见#3)。 2. 有没有办法在回复中添加描述? 我试过 + Response 403 If the request request is made with HTTP instead of HTTPS. 但这只是将文本添加为​​正文响应。 3. 描述我的回复的不同领域 如果我返回 JSON,我想分别描述每个字段、它的类型和它的用途。 有没有办法做到这一点? 谢谢! 回答1 让我们一起看一下 #1 和 #3,因为它们密切相关: 有效载荷字段说明 目前没有专门的语法来讨论有效载荷的实际字段(模型、响应或请求)。 现在取决于你如何使用任何你喜欢的 Markdown 语法来描述它。 计划是提供一个 Markdown 语法来讨论这些字段/参数,如下所示: JSON: { "id": 1, "name": "A green door", "price": 12.50, "tags": ["home", "green"] } 及其在蓝图中的描述: - id: 1

2021-11-28 07:17:22    分类:技术分享    apiblueprint

Response description and POST parameters in API Blueprint

I am trying out API Blueprint and found some things, which are not quite clear to me. 1. How can I document POST body parameters? There is + Parameters but it just documents query parameters. If I now want to describe a POST API I can't document POST parameters (application/x-www-form-urlencoded). The same goes for JSON (see #3). 2. Is there a way to add a description to a response? I tried + Response 403 If the request request is made with HTTP instead of HTTPS. But this just adds the text as the body response. 3. Describe the different fields of my response If I return JSON I want to

2021-11-22 07:17:33    分类:问答    apiblueprint

Trying to describe the request and response using Data Structures in API Blueprint

I'm trying to document an endpoint with API Blueprint, using the new Attributes and DataStructures sections of the spec. My request payload looks like this: { "url": "http://requestb.in/11v7i7e1", "active": true, "types": [ { "name": "sales", "version": "2.0" }, { "name": "products", "version": "2.0" } ] } My response payload looks something like that: { "data": { "id": "dc85058a-a683-11e4-ef46-e9431a15be8c", "url": "http://requestb.in/11v7i7e1", "active": true, "types": [ { "name": "products", "version": "2.0" }, { "name": "sales", "version": "2.0" } ] } } I tried the following API Blueprint

2021-11-21 17:46:02    分类:问答    api   apiblueprint   apiary.io   apiary   MSON

在 API 蓝图中表示文件上传(Represent File Uploads in API Blueprints)

问题 我们有一个 API 端点,可以在其中上传图像文件以及文件名(字符串)和描述(字符串)。 Apiary / API Blueprints 不允许我有类似的东西: + Request (multipart/form-data) + Headers Authorization: [key] + Attributes + name (string, required) - A human-readable name of the Catalog Item + description (string, optional) - A human readable description of the Catalog Item + image (file, optional) - An image file corresponding to the Catalog Item 我得到: base type 'file' is not defined in the document 有没有办法在 API Blueprints 中表示多部分/表单数据,例如上述内容?

2021-10-18 19:10:16    分类:技术分享    apiblueprint   apiary.io   apiary

Apiary.io 和/或 API Blueprint 是否支持 API 版本控制?(Does Apiary.io and/or API Blueprint support api versioning?)

问题 api blueprint 或 Apiary.io 是否支持对 API 进行版本控制的概念? 特别是,我通过 URI 对我的 API 进行版本控制,如下所示: GET /api/v2/SomeResource/ 在上面的示例中,这意味着我正在调用 API 的第 2 版(“v2”)。 api蓝图支持这个吗? 如何记录给定操作或整个 API 的多个版本? 回答1 您可以使用HOST标头来表示: HOST: http://example.com/api/v2将使用/api/v2为所有资源添加前缀。 在 API 蓝图中,如果您使用 URL 前缀,则 API 被认为是不同的,因此您应该为它们使用不同的蓝图。 如果您使用带有版本后缀的媒体类型来执行此操作,您只需在标头中指定正确的Content-Type ,它们将被正确用于模拟服务器中的内容协商。

2021-09-29 03:07:09    分类:技术分享    rest   apiblueprint   apiary

MSON在蓝图中描述对象属性(MSON to describe object attributes in blueprint)

问题 我有一个类似于这里描述的问题。 我有一个看起来像这样的 JSON: { "photos": [ { "key": "y37dmj10jkwof/moOIUB8912JKVgh", "caption": "A world of gamers.", "tags": [ "game", "japan" ], "attributes": { "copyright": true, "use": [ "public", "private" ] } } ] } 我正在尝试使用 MSON 描述属性,以呈现蓝图。 但是,我并不成功。 这是我的尝试: + Attributes (required, object) + photos (required, array) + (object) + key (required, string) - Photo key + caption (required, string) - Photo caption + tags (required, array) + game (string) + japan (string) + attributes (required, object) + (object) + copyright: true (required, boolean) + uses (required, array) + public

2021-09-23 18:36:38    分类:技术分享    apiblueprint   apiary.io   apiary   MSON

使用 Apiary 创建模拟服务 API(Create Mock Service API using Apiary)

问题 我正在尝试创建用于测试目的的模拟 api 服务。 我们已经在另一个团队中使用 Apiary,所以我从那里开始。 到目前为止,我注意到如果我想要两个单独的调用需要模拟两个请求。 例如,要获取 ID 为 1 和 2 的注释,需要明确写出如下响应: /notes/1 /notes/2 有没有办法避免这种情况? 不可否认,我仍在努力创建蓝图。 回答1 看看 private-e9e59-pingdomcheck.apiary-mock.com/v1/gists/1。 这里的数字1是{id} 。 您当然只能得到一般定义的响应(就像我使用 id 42 一样)。 现在在 MSON 中有更多的事情要做。 一旦发布,请求中不同参数的不同回复将是可能的。

2021-09-18 17:42:55    分类:技术分享    apiblueprint   apiary.io   apiary

创建 Blueprint API 文档时如何格式化 URL 中基于哈希的参数?(How to format hash-based parameters in the URL when creating Blueprint API doc?)

问题 使用 Rails 方法在 URL 的参数中添加哈希,如下所示: http://api.example.com?person[first]=Jane&person[last]=Doe&person[email]=jane@doe.com 如何格式化 API Blueprint 文档以容纳可用哈希列表? 参数 person[first] (required, string, Jane ) ...名字 这在我执行文档时是不合法的。 欢迎任何想法或提示! 回答1 根据 https://tools.ietf.org/html/rfc3986#section-3.2.2,您必须在 URI 中转义 []。 因此,您需要执行以下操作: 参数 person%5Bfirst%5D(必需,字符串,Jane)... 如果您在蓝图中对 URI 进行模板化,则还必须对那里的 [] 进行转义。 仅供参考,Apiary.io 中代码生成的原始文档中存在一个错误(如果您正在使用它),并且此时生成的 URI 无法正确处理转义。 你可以打开 Beta 文档,它没有这个问题。

2021-09-15 21:56:08    分类:技术分享    ruby-on-rails   formatting   apiblueprint

为我们在 Apiary.io 中的每个响应指定描述(Specify description for every response we have in Apiary.io)

问题 是否可以为某个请求的每个响应指定描述? 假设,我们有一个请求 ### Retrieve resource [GET] + Headers If-None-Match: "Version1" 和 2 个回复 + Response 200 (application/xml) + Headers ETag: "Version2" + Body <Xml> <A> <B /> <C /> </A> </Xml> + Response 304 (application/xml) 我想要的是在此处指定描述(请注意+ Response行下的注释): + Response 200 (application/xml) In case if the resource hasn't changed + Headers ETag: "Version2" + Body <Xml> <A> <B /> <C /> </A> </Xml> + Response 304 (application/xml) In case if the resource has changed 是否可以? 回答1 目前没有办法在 API Blueprint 中表达这样的逻辑。 您始终可以在相应的响应中或在动作本身下“通过口”来描述它。 例如: # Resource [/1] ## Action [GET]

2021-08-12 04:41:43    分类:技术分享    rest   apiary.io   apiblueprint