2

我目前正在尝试生成我的 API，但在为列表组中的第一个方法添加描述时遇到了一些困难。我可以为组中的所有其他方法添加描述，而不是第一个。

我在下面附上了一张我希望它看起来如何的图片，但我无法使用 RAMLtoHTML 生成器来实现这一点。

描述问题

下面是我在主文件中使用的代码。该文件包含我遇到问题的文件。我在想也许我可以改变它？

#%RAML 0.8
title: Hubs
baseUri: https://apis.3dissue.com/hubsdashboard/api/{version}
version: v1
mediaType: application/json
documentation:
  - title: Getting Started
    content: !include md/getting_started.md
  - title: Overview
    content: !include md/overview.md
  - title: Creating a Hub
    content: !include md/creating_hub.md
  - title: Adding Social Sources to a Hub
    content: !include md/social_sources.md
  - title: Adding an Article to a Hub
    content: !include md/articles.md
traits: !include traits.raml


#Hubs
/hubs: !include calls/hubs.raml

这是我要在下面添加描述的文件。正如你所看到的，我已经添加了一个列表描述，如果我尝试在这里添加一个方法描述，那么我会从解析器那里得到一个“描述”已经定义的抱怨。

is: [appkey]
displayName: User Hubs
description: This group contains methods that will allow you to create, manage, and retrieve details of one or more hubs.
get:
  description: Returns a JSON array containing details of hubs associated with the user account.
  queryParameters:
    page:
      description: The page number to be returned within the paged results. By default, this will return the first page.
      type: number
      default: 1
    page_size:
      description: The number of elements to return per page. By default, a total of 10 elements will be returned. This parameter should be used in combination with the page parameter for setting up paged results.
      type: number
      default: 10
    related:
      description: Determines whether to return related objects. If set to 1, all child elements for each hub in the list will be returned including any sections and sources.
      type: boolean
      default: 0
  body:
    example: !include ../php/getListOfHubs.php
  responses:
    200:
      body:
        application/json:
          example: !include ../json/hubs.json
post:
  description: This method will allow you to create a new hub.
  body:
      example: !include ../php/createHub.php
  responses:
    200:
      body:
        application/json:
          example: !include ../json/hub_create_response.json
/{hub_id}:
  description: The following methods can be used to manage or retrieve details for a given hub.
  uriParameters:
    hub_id:
      description: A string value used to uniquely identify a hub.
      type: string
  get:
    description: Returns a JSON array containing details for the given hub.
    body:
      example: !include ../php/getHub.php
    responses:
      200:
        body:
          application/json:
            example: !include ../json/hub.json
  put:
    description: This method will allow you to update the display name of the given hub.
    body:
      example: !include ../php/updateHub.php
    responses:
      200:
        body:
          application/json:
            example: !include ../json/hub.json
  delete:
    description: This method will allow you to delete the selected hub. Deleting a hub will not remove any sources from your account.
    body:
      example: !include ../php/deleteHub.php
    responses:
      204:
        description: No response body

有没有人有解决方法？我尝试在包含之前的第一个文件中添加描述，但得到解析器错误。我也尝试在第二个文件中移动 /hubs 声明，但我可以让它解析的唯一方法是在方法调用 URL 中添加一个额外的字符，这远非理想。

4

0 回答 0