2

我们正在利用 Apiary.io 的 API 蓝图使用 HAL+JSON 开发一个新的 API。我们一直在蓝图本身的响应中使用 JSON。我正在测试改用 MSON,但遇到了数组对象的问题。

这是 API 蓝图代码。一切都很好,除了curies数组(朝向底部),它包含一个object.

FORMAT: 1A

# Content API
An API for retrieving content from NBC News Group.

# Group Root resource
The starting point for the Content API.

## Root Resource [/]

### Request root resource [GET]
+ Response 200 (application/hal+json)

    + Attributes (required, object)
        + _links (object) - Linked resources in HAL
              + self (required, object) - Self link to current document
                  + href: / (required, string) - URI of this resource
                  + profile: `http://domain.com/docs/profiles/root` (required, string) - URI to profile description for this resource
              + `nbng:content` (object) - Link relation to all content
                  + href: `http://apiary-mock.com/content` (required, string) - URI to content
                  + title: Browse all NBC News Group content (required, string) - title of the link relation
              + `nbcng:publishers` (object) - Link relation to all publishers
                  + href: `http://apiary-mock.com/publishers` (required, string)  - URI to publishers
                  + title: Browse all NBC News Group publishers (required, string) - title of the link relation
              + `nbcng:publisher` (object) - Link relation to an individual publisher
                  + href: `http://apiary-mock.com/publisher/{id}` (required, string) - URI to an individual publisher, with `{id}` query string param
                  + templated: true (required, boolean) - Notes if the link has a URI template associated to it
                  + title: Get a publisher by name (required, string) - title of the link relation
              + curies (required, array) - Link relation to documentation
                  + (object)
                      + href: `http://www.domain.com/docs/relation/nbcng/{rel}` (required, string) - URI to documentation
                      + name: nbcng (required, string) - prefix of the link relation documentation is tied to
                      + title: NBC News Group Link Relation (required, string) - title of the link relation
                      + templated: true (required, boolean) - Notes if the link has a URI template associated to it
        + welcome: Welcome to the NBC News Group Content API (required, string) - Welcome message for resource

对于该curies数组,JSON 格式的 API 蓝图输出返回:

"curies": [
  {
    "undefined": null
  }
]

当预期的 JSON 看起来像这样时:

"curies": [
      {
        "href": "http://www.nbcnewsdigitaldev.com/docs/relation/nbcng/{rel}",
        "name": "nbcng",
        "title": "NBC News Group Link Relation",
        "templated": true
      }
    ]

据我从 MSON 规范中可以看出,curies数组和对象的语法是正确的。

希望获得类似 MSON 探索的人们的任何反馈。

4

1 回答 1

1

我在 API Blueprint、MSON和嵌套结构中遇到了相当多的奇怪行为。在这种情况下,您会假设您所做的事情会起作用,或者可能将其指定为

+ curies (required, array) - Link relation to documentation
    + Attributes (object)
         + href: `http://www.domain.com/docs/relation/nbcng/{rel}` (required, string) - URI to documentation
         + name: nbcng (required, string) - prefix of the link relation documentation is tied to
         + title: NBC News Group Link Relation (required, string) - title of the link relation
         + templated: true (required, boolean) - Notes if the link has a URI template associated to it

这对我来说仍然是破碎的。但是,如果您使用似乎可以正确渲染的数据结构

FORMAT: 1A

# Content API
An API for retrieving content from NBC News Group.

# Group Root resource
The starting point for the Content API.

## Root Resource [/]

### Request root resource [GET]
+ Response 200 (application/hal+json)

    + Attributes (required, object)
        + _links (object) - Linked resources in HAL
              + self (required, object) - Self link to current document
                  + href: / (required, string) - URI of this resource
                  + profile: `http://domain.com/docs/profiles/root` (required, string) - URI to profile description for this resource
              + `nbng:content` (object) - Link relation to all content
                  + href: `http://apiary-mock.com/content` (required, string) - URI to content
                  + title: Browse all NBC News Group content (required, string) - title of the link relation
              + `nbcng:publishers` (object) - Link relation to all publishers
                  + href: `http://apiary-mock.com/publishers` (required, string)  - URI to publishers
                  + title: Browse all NBC News Group publishers (required, string) - title of the link relation
              + `nbcng:publisher` (object) - Link relation to an individual publisher
                  + href: `http://apiary-mock.com/publisher/{id}` (required, string) - URI to an individual publisher, with `{id}` query string param
                  + templated: true (required, boolean) - Notes if the link has a URI template associated to it
                  + title: Get a publisher by name (required, string) - title of the link relation
              + curies (required, array) - Link relation to documentation
                  + Attributes (Cury)
        + welcome: Welcome to the NBC News Group Content API (required, string) - Welcome message for resource


# Data Structures

## Cury (object)
+ href: `http://www.domain.com/docs/relation/nbcng/{rel}` (required, string) - URI to documentation
+ name: nbcng (required, string) - prefix of the link relation documentation is tied to
+ title: NBC News Group Link Relation (required, string) - title of the link relation
+ templated: true (required, boolean) - Notes if the link has a URI template associated to it

哪个呈现端点的响应为

{
  "_links": {
    "self": {
      "href": "/",
      "profile": "http://domain.com/docs/profiles/root"
    },
    "nbng:content": {
      "href": "http://apiary-mock.com/content",
      "title": "Browse all NBC News Group content"
    },
    "nbcng:publishers": {
      "href": "http://apiary-mock.com/publishers",
      "title": "Browse all NBC News Group publishers"
    },
    "nbcng:publisher": {
      "href": "http://apiary-mock.com/publisher/{id}",
      "templated": true,
      "title": "Get a publisher by name"
    },
    "curies": [
      {
        "href": "http://www.domain.com/docs/relation/nbcng/{rel}",
        "name": "nbcng",
        "title": "NBC News Group Link Relation",
        "templated": true
      }
    ]
  },
  "welcome": "Welcome to the NBC News Group Content API"
}
于 2015-09-15T16:06:48.990 回答