标签: apiary

我尝试使用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 Status:", resp.Status())
    fmt.Println("response Headers:", resp.HttpResponse().Header)
    fmt.Println("response Body:", resp.RawText()) …

我正在尝试使用API​​ Blueprint记录端点,使用规范的新Attributes和DataStructures部分.

我的请求有效负载如下所示:

{
    "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 Blueprint markdown:

FORMAT: 1A

# Vend REST API 2.0

# Group Webhooks

## api/2.0/webhooks [/webhooks]

### List all Webhooks [GET]
Returns a list of Webhooks created by the …

我试图通过不同的参数获得不同的响应,但有些东西不起作用.

这是我的API:

## Question [/questions/{question_id}]

A Question object has the following attributes:

+ Parameters
    + question_id: `1` (number, required) - ID of the Question in form of an integer

### View a Questions Detail [GET]

+ Request

+ Header

    X-Custom-Header : 1

+ Response 200 (application/json)

        {
            "id": "1",
            "name": "Marco"
        }


+ Request

+ Header

    X-Custom-Header : 2

+ Response 200 (application/json)

        {
            "id: "2",
            "name": "Lucas"
        }

但是在调用/ questions/1或/ questions/2时,响应始终是相同的:

{
    "id": "1",
    "name": "Marco"
}

怎么了？

谢谢

我想记录实际的JSON字段本身代表什么.

我已经记录了GET语句和参数,但这并没有为用户提供完整的文档.

因此,在下面的示例中,我将如何添加有关"OtherFields"的注释.这支持吗？或者我是否需要在其他地方制作配套文件.

## View Applications [/cat{?sort}{&order}{&page}]
### List all Applications 
### Get List of Applications [GET]
+ Parameters
    + sort (optional, string) ... `sort` parameter is used to specify which criteria to use for sorting. One of the following strings may be used: 
    `"NAME", 
    "RATING", "QUALITY" ,
    "RISKLEVEL", `

    + order (optional, string) ... `order` parameter is used to specify which order to use if sorting is used. One of the following strings may be used: 
    `"ASC", 
    "DESC"`

    + …

我想要的是更改与API Doc关联的主电子邮件,因此当我与其他人共享该文档时,他们会看到新的电子邮件,而不是我的.那封新电子邮件有一个apiary.io,这就是为什么我在谈论所有权转移.

嗨我正在使用Apiary维护我的REST API文档,因为我们的代码库正在增长,我们的API文档越来越大.将所有API放在单个蓝图文件中变得非常困难,我们是否可以将它们正确地组织成多个文件并在蜂房内显示它们.

我的数据结构定义如下:

# Data Structures

## PlayerRank (object)
Represents the minimum amount of data the the client needs to send to give rank information about a particular Player in a particular Played Game.
+ playerId (number, required) - NemeStats unique identifier for the Player.
+ gameRank (number, required) - The corresponding rank of the Player in this Played Game. A rank of 1 means the Player got first place, 2 means second place, and so on.
+ pointsScored (number, optional) - …

我正在编辑我正在处理的项目的一些Apiary文档,并且需要表示我的一个API调用的参数是一个日期时间字符串.蜂房似乎在扼杀这个参数的格式,所以我想知道在Apiary中记录这个参数的建议方法是什么.

为了演示,我从Apiary获取了标准的默认文档并修改了Choice文档以获取类似的datetime对象:

## Choice [/questions/{question_id}/choices/{choice_id}/{datetime}]

+ Parameters
    + question_id: 1 (required, number) - ID of the Question in form of an integer
    + choice_id: 1 (required, number) - ID of the Choice in form of an integer
    + datetime: 2015-05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) associated with this choice

最终结果如下:

datetime
05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) that all returned events should be greater than or equal to Example: 2015.

这显然是错误的,甚至写下示例值.破折号(-)是一个特殊的角色,在这里引起悲伤.这样做的推荐方法是什么？

我有一个API调用,响应200 OK并返回一个HTML.我想将此添加到我的API文档中(特别是因为我使用dredd验证它,除非我提供预期的响应体,测试失败).我怎么会在Swagger这样做？

---更多细节---我对API调用的响应是200 OK并且有一行响应正文:

<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>

我可以使用以下格式轻松定义蓝图中的响应主体:

 + Response 302 (text/html; charset=utf-8)

     + Body

         `<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>`

但我不知道如何在Swagger中做到这一点.我能找到的几乎所有例子都是针对应用程序/ json响应(可以理解),我无法猜测这种响应的正确语法.

我的文档中相关的招摇文本是这样的(到目前为止没有指定响应主体,因此空主体dredd失败,因为响应主体应该是<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>):

# this is my API spec in YAML
swagger: '2.0'
info:
  title: My API (Swagger)
  description: blablabla
  version: "1.0.0"
# the domain of the service
host: my.domain.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /
produces: …

我们有一个 API 端点，可以在其中上传图像文件以及文件名（字符串）和描述（字符串）。

养蜂场/API 蓝图不允许我拥有类似的东西：

+ 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 蓝图中表示多部分/表单数据（例如上面的内容）？