Question

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

我在下面附上了我想要它的外观，但我无法使用RAMLtoHTML生成器实现这一目标。

Description Issue

以下是我在主文件中使用的代码。此文件包含我遇到问题的文件。我想也许我可以改变一些东西？

#%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

这是我想在下面添加说明的文件。正如您所看到的，我已经添加了一个列表描述，如果我尝试在此处添加方法描述，那么我会从解析器中收到一个抱怨＆＃34; description＆＃34;已定义。

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中添加一个额外的字符，这远非理想。

在RAML中添加组和方法描述

0 个答案: