天道酬勤,学无止境

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 ,它们将被正确用于模拟服务器中的内容协商。

受限制的 HTML

  • 允许的HTML标签:<a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • 自动断行和分段。
  • 网页和电子邮件地址自动转换为链接。

相关推荐
  • Does Apiary.io and/or API Blueprint support api versioning?
    Does api blueprint or Apiary.io support the notion of versioning your API? In particular, I'm versioning my API via the URI like this: GET /api/v2/SomeResource/ In the example above, this means I'm calling version 2 ("v2") of the API. Does api blueprint support this? How can I document multiple versions of a given action or the entire API?
  • 为我们在 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]
  • 是否可以将表格放在markdown文件中居中?(Is it possible to center tables in a markdown file?)
    问题 我有一张桌子: | This | Is | A | Table | | :--- | -- | - | ----: | | foo | ba | r | elbaT | 我希望表格显示在Markdown文件的中心,而不是左对齐。 我不是要对齐文本,而是要对齐整个表格本身。 我需要依靠HTML / CSS来实现自己想要的吗? 这是针对Apiary.io项目的。 回答1 如果您使用标准文档,请使用<center>标签。 蓝图 FORMAT: 1A HOST: http://www.google.com # Tables Notes API is a *short texts saving* service similar to its physical paper presence on your table. <center> | Tables | Are | Cool | |----------|:-------------:|------:| | col 1 is | left-aligned | $1600 | | col 2 is | centered | $12 | | col 3 is | right-aligned | $1 | </center> # Group Notes (...) 预习 如果您使用“新文档” ,则无法将表格居中(因为表格占据了整个列的宽度)
  • 创建 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 文档,它没有这个问题。
  • AngularJS 量角器 E2E 模拟(AngularJS Protractor E2E Mocking)
    问题 我有一个 Angular SPA 从节点后端检索其数据。 由于节点项目完全被测试覆盖,我想模拟 Angular HTTP 调用。 (我不想开始讨论一般的功能/烟雾测试,谢谢)。 我想要的是s.th。 像这样 Api = $injector.get('Api'); sinon.mock(Api, 'getSomethingFromServer').andRespondWith({foo: 'bar'}) assert(Api.getSomethingFromServer.wasCalledOnce); 但无论如何我都找不到好的解决方案。 我发现了几个关于同一问题的帖子。 比如这个。 由于量角器变化很大且频繁,我只想在这里询问是否有人找到了模拟 HTTP 请求的适当解决方案。 回答1 我们目前正在使用 http://apiary.io 除了能够“模拟”您的回复之外,您还可以获得一个不错的 API 描述作为奖励! 我们所做的是针对代理运行 Angular 应用程序,这取决于我们是在开发中还是在生产中,可以转发到真正的后端或 apiary 提供的后端。 回答2 我同意之前的回答。 对于 Protractor 频繁更改的解决方案是将后端与被测系统完全去相关,无论它是模拟、存根还是假的。 困难在于保持与真实后端的强一致性,但并不是说这比试图保持不断变化的 angular
  • Specify description for every response we have in Apiary.io
    Is it possible to specify description for every response to some request? Suppose, we have a request ### Retrieve resource [GET] + Headers If-None-Match: "Version1" And 2 responses + Response 200 (application/xml) + Headers ETag: "Version2" + Body <Xml> <A> <B /> <C /> </A> </Xml> + Response 304 (application/xml) What I would like is to specify description like here (please note comments right under + Response lines): + 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
  • 为 ASP.Net Web API 生成 JSON Schema(Generate JSON Schema for ASP.Net Web API)
    问题 我正在寻找为 WebAPI 生成 JSON 模式,包括来自 XML 注释的文档。 主要是这样我就可以将其导入我们的 API 文档(使用 apiary.io)我设法通过添加 swagger(和 swashbuckle)然后在每个服务上使用原始链接来获得解决方案 - 但理想情况下我会就像一些更清晰的东西,它适用于所有 api(这必须针对每个服务/控制器完成),并且没有那么多依赖项。 在我去看看 swagger 是如何做到这一点并看看它是否可以被提取之前,最好知道是否有现有的方法可以做到这一点? 回答1 是的,您可以依赖 Swagger 并且有一个名为 swashbuckle 的扩展,您可以轻松地将它与 Web API 一起使用,请查看这篇文章 http://bitoftech.net/2014/08/25/asp-net-web-api-文档使用招摇/
  • 如何在Go中的POST请求中发送JSON字符串(How do I send a JSON string in a POST request in Go)
    问题 我尝试使用Apiary,并制作了一个通用模板以将JSON发送到模拟服务器并具有以下代码: package main import ( "encoding/json" "fmt" "github.com/jmcvetta/napping" "log" "net/http" ) func main() { url := "http://restapi3.apiary.io/notes" fmt.Println("URL:>", url) s := napping.Session{} h := &http.Header{} h.Set("X-Custom-Header", "myvalue") s.Header = h var jsonStr = []byte(` { "title": "Buy cheese and bread for breakfast." }`) var data map[string]json.RawMessage err := json.Unmarshal(jsonStr, &data) if err != nil { fmt.Println(err) } resp, err := s.Post(url, &data, nil, nil) if err != nil { log.Fatal(err) } fmt.Println("response
  • 在哪里放置资源特定的逻辑(where to place resource specific logic)
    问题 你能帮我考虑在 AngularJS 中放置资源(服务)特定业务逻辑的位置吗? 我觉得在我的资源上创建一些类似模型的抽象应该很棒,但我不确定如何。 API调用: > GET /customers/1 < {"first_name": "John", "last_name": "Doe", "created_at": '1342915200'} 资源(在 CoffeScript 中): services = angular.module('billing.services', ['ngResource']) services.factory('CustomerService', ['$resource', ($resource) -> $resource('http://virtualmaster.apiary.io/customers/:id', {}, { all: {method: 'GET', params: {}}, find: {method: 'GET', params: {}, isArray: true} }) ]) 我想做类似的事情: c = CustomerService.get(1) c.full_name() => "John Doe" c.months_since_creation() => '1 month' 非常感谢您的任何想法。 亚当 回答1
  • 使用httpClient.GetAsync时添加标题(Adding headers when using httpClient.GetAsync)
    问题 我正在Windows Store应用程序项目中实现由Apiary.io的其他同事制作的API。 它们显示了我必须实现的方法示例: var baseAddress = new Uri("https://private-a8014-xxxxxx.apiary-mock.com/"); using (var httpClient = new HttpClient{ BaseAddress = baseAddress }) { using (var response = await httpClient.GetAsync("user/list{?organizationId}")) { string responseData = await response.Content.ReadAsStringAsync(); } } 在这种方法和其他方法中,我需要具有一个标头,该标头带有我之前获得的令牌。 这是邮递员(chrome扩展名)的图片,其中包含我正在谈论的标头: 如何将“授权”标头添加到请求中? 回答1 当将GetAsync与HttpClient一起使用时,您可以像这样添加授权标头: httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "Your Oauth
  • Adding headers when using httpClient.GetAsync
    I'm implementing an API made by other colleagues with Apiary.io, in a Windows Store app project. They show this example of a method I have to implement: var baseAddress = new Uri("https://private-a8014-xxxxxx.apiary-mock.com/"); using (var httpClient = new HttpClient{ BaseAddress = baseAddress }) { using (var response = await httpClient.GetAsync("user/list{?organizationId}")) { string responseData = await response.Content.ReadAsStringAsync(); } } In this and some other methods, I need to have a header with a token that I get before. Here's an image of Postman (chrome extension) with the header
  • 用 $resource 正确包装新的域对象实例(Properly wrap new domain object instance with $resource)
    问题 作为 $resource 返回 [OO] 对象数组的后续操作,如何正确包装 $resource 中的新域对象实例 app.factory('NoteResource', ['$resource', function($resource) { var res = $resource('http://okigan.apiary.io/notes/:id', null, ...); res.newInstance = function() { return angular.extend(new Note(), res); }; } NoteResource.newInstance() 应使用标准的 $save/$update 方法返回对象。 最好修改 plunker 并观看流量,然后“新笔记”按钮应该可以正常工作。 回答1 更新 这是一种您可以继续将Note构造函数合并到$resource服务中的方法... 给工厂返回的对象添加一个新的实例方法: res.getNew = function(){ var newNote = new Note(); newNote.id = undefined; // new note doesn't have id set newNote.checked = undefined; // don't need this data passed to
  • Generate JSON Schema for ASP.Net Web API
    I'm looking to generate JSON Schema for a WebAPI, including documentation from the XML comments. Its primarily so that I can then import that into our API docs (using apiary.io) I've managed to get a workaround solution by adding swagger (and swashbuckle) and then using the raw link on each service - but ideally I'd like something a bit cleaner, that works across all apis (this has to be done per service / controller), and didnt have so many dependencies. Before I go and look at how swagger is doing this and seeing if it can be extracted, would be good to know if there are existing ways to do
  • WooCommerce API OAuth in python
    I'm trying to do a basic implementation of the WooCommerce API OAuth client in python following what the documentation says: http://docs.woocommercev2.apiary.io/introduction/authentication/over-http. This is what I have so far: import requests import random import string import time from hashlib import sha1 import hmac import binascii import re from urllib import quote, urlencode def uksort(d, func): s = {} for k in sorted(d.keys(), cmp = func): s[k] = d[k] return s class WooCommerce(object): def __init__(self, consumer_key, consumer_secret, endpoint): self.consumer_key = consumer_key self
  • How do I send a JSON string in a POST request in Go
    I tried working with Apiary and made a universal template to send JSON to mock server and have this code: package main import ( "encoding/json" "fmt" "github.com/jmcvetta/napping" "log" "net/http" ) func main() { url := "http://restapi3.apiary.io/notes" fmt.Println("URL:>", url) s := napping.Session{} h := &http.Header{} h.Set("X-Custom-Header", "myvalue") s.Header = h var jsonStr = []byte(` { "title": "Buy cheese and bread for breakfast." }`) var data map[string]json.RawMessage err := json.Unmarshal(jsonStr, &data) if err != nil { fmt.Println(err) } resp, err := s.Post(url, &data, nil, nil)
  • 带有请求正文android的HttpGet(HttpGet with request body android)
    问题 我尝试通过 HttpGet 在服务器上发出请求。 但在消息正文中应该是一个 json 对象。 下面的代码不起作用,因为 unit_id 和 sercret_key 未在正文消息中发送到服务器。 我该怎么做? JSON 对象: { "unit_id": 12345, "secret_key": "sdfadfsa6as987654754" } 我的代码: private HttpResponse makeRequest(int id, String secretKey) throws Exception { BasicHttpParams params = new BasicHttpParams(); params.setParameter("id", id); params.setParameter("secret_key", secretKey); httpget.setHeader("Accept", "application/json"); httpget.setParams(params); httpget.setHeader("Content-type", "application/json"); // Handles what is returned from the page return httpclient.execute(httpget); } 编辑:在
  • python中的WooCommerce API OAuth(WooCommerce API OAuth in python)
    问题 我正在尝试按照文档所述在 python 中执行 WooCommerce API OAuth 客户端的基本实现:http://docs.woocommercev2.apiary.io/introduction/authentication/over-http。 这是我到目前为止: import requests import random import string import time from hashlib import sha1 import hmac import binascii import re from urllib import quote, urlencode def uksort(d, func): s = {} for k in sorted(d.keys(), cmp = func): s[k] = d[k] return s class WooCommerce(object): def __init__(self, consumer_key, consumer_secret, endpoint): self.consumer_key = consumer_key self.consumer_secret = consumer_secret self.endpoint = endpoint def _make_request(self
  • 方形改装服务器模拟测试(Square retrofit server mock for testing)
    问题 使用方形改造框架时,模拟服务器进行测试的最佳方法是什么。 可能的方式: 创建一个新的改装客户端,并在RestAdapter.Builder()。setClient()中进行设置。 这涉及解析Request对象,并将json作为Response对象返回。 将这个带注释的接口实现为模拟类,并使用它代替RestAdapter.create()提供的版本(不会测试gson序列化) ? 理想情况下,我想让模拟服务器提供json响应,以便我可以同时测试gson序列化。 任何例子将不胜感激。 回答1 模拟翻新2.0请求测试 由于旧的机制(例如,创建MockClient类并从Client实现它)在Retrofit 2.0中不再起作用,因此在此我描述了一种新的实现方式。 您现在需要做的就是为OkHttpClient添加自定义拦截器,如下所示。 FakeInterceptor类仅覆盖intercept方法,如果应用程序处于DEBUG模式,则返回给定JSON。 RestClient.java public final class RestClient { private static IRestService mRestService = null; public static IRestService getClient() { if(mRestService == null) { final
  • HttpGet with request body android
    I try to make a request on server by HttpGet. But in message body should be a json object. Code below is not working because unit_id and sercret_key are not sent on server in body message. How can I do it? JSONObject: { "unit_id": 12345, "secret_key": "sdfadfsa6as987654754" } My code: private HttpResponse makeRequest(int id, String secretKey) throws Exception { BasicHttpParams params = new BasicHttpParams(); params.setParameter("id", id); params.setParameter("secret_key", secretKey); httpget.setHeader("Accept", "application/json"); httpget.setParams(params); httpget.setHeader("Content-type",
  • where to place resource specific logic
    Can you help me please to consider where to place resource (service) specific business logic in AngularJS. I feel it should be great to create some model-like abstraction over my resource, but I'm not sure how. API call: > GET /customers/1 < {"first_name": "John", "last_name": "Doe", "created_at": '1342915200'} Resource (in CoffeScript): services = angular.module('billing.services', ['ngResource']) services.factory('CustomerService', ['$resource', ($resource) -> $resource('http://virtualmaster.apiary.io/customers/:id', {}, { all: {method: 'GET', params: {}}, find: {method: 'GET', params: {}