％RAML 1.0

Question

我在mulesoft api设计师中使用RAML 1.0。

我想使用类型/属性来描述我的api响应，并且还启用模拟服务，这样我就可以运行api并获得示例响应。我想如果我给类型一个示例值，模拟服务就能生成示例json响应。这是我的测试raml

#%RAML 1.0
title: Test
baseUri: https://mocksvc.mulesoft.com/mocks/<removed>

types:

  Email:
    description: Email address
    example: Steve@test.com

/user:
  get:
    responses:
      200:
        body:
          application/json:
            properties:
              email: Email

当我通过模拟服务运行api时，我希望我的响应主体是这样的：

{
  "email": "Steve@test.com"
}

但服务报告它没有任何信息并在正文中返回

{
  "message": "RAML had no response information for application/json"
}

Answer 1

不，这将是一个很酷的功能，但它不会那样工作。

您需要在响应中添加示例：

...
types:

  Email:
    description: Email address

/user:
  get:
    responses:
      200:
        body:
          application/json:
            properties:
              email: Email
            example: { "email": "Steve@test.com" }

Answer 2

我们需要提供我们期望的示例类型，请查看此链接http://raml.org/developers/raml-200-tutorial

下面刚刚在响应正文中添加了示例，我们可以在其中提供多个结果。

％RAML 1.0

标题：测试 baseUri：https://mocksvc.mulesoft.com/mocks/

类型：

电子邮件：描述：电子邮件地址例如：Steve@test.com

/用户：得到：对策： 200：身体：应用程序/ JSON：特性：电邮：电邮例： “电子邮件”：[ {“email”：“Steve@test.com”} ]

Answer 3

Raml 1.0中的类型标记更强大。您可以根据舒适度设计自定义类型，并提高代码的可信度

#%RAML 1.0
title: Brochure
version: v1
baseUri: https://mocksvc.mulesoft.com/mocks/63063930-851d-41cc-b021-36d8a435d800 # baseUri: http://localhost:8080
protocols: HTTP
mediaType: application/json
types:
  ModelTree:
    type: object
    properties:
      modelTreeReference: string
      brand: string
      series?: string
      constructionSeries?: string
      bodyType?: string
      AGModelCode?: string
      UKModelCode?: string
      levelCode?: number
  Brochure:
    type: object
    properties:
      recordNumber: number
      partNumber: number
      name: string
      brand: string
      brochureType: string
      CRMGroup: string
      CRMSubGroup: string
      isActiveIndicator: string
      modelTree: ModelTree
  Status:
    type: object
    properties:
      responseStatus:
        enum: [COMPLETE, ERROR, FATAL]
      responseId: number
  Transaction:
    type: object
    properties:
      status: Status
      data:
        type: object
        properties:
          brochures?: Brochure[]
/brochures:
  get:
    responses:
      200:
        description: Status and a list of Brochures
        body:
          application/json:
            example: {
              status: {
                responseStatus: 'COMPLETE',
                responseId: 123
                },
              data: {
                brochures: [{
                    recordNumber: 1,
                    partNumber: 56,
                    name: "Activity Brochure",
                    brand: "My Brand Ltd",
                    brochureType: "HARDCOPY",
                    CRMGroup: "Sales",
                    CRMSubGroup: "Lifestyle/Access",
                    isActiveIndicator: "N",
                    modelTree: {
                      modelTreeReference: "My Brand",
                      brand: "My Brand Ltd",
                      levelCode: 1
                      }
                  }
                ]
                }
              }
            type: Transaction

Answer 4

我使用带有表单编码主体的示例遇到了类似的问题。规范和RAML 200 tutorial中针对application / json编码的响应给出的示例不适用于application / x-www-form-urlencoded。

此类型

types:
  hub:
    type: object
    properties:
      callback: string
      mode: 
        enum: ["subscribe", "unsubscribe"]
      topic: string

与application / json正文和示例一起正常使用

/subv1json:
  post:
    description: "Subscribes to a topic"
    body:
      application/json:
        type: hub
        example: 
          {
            "callback": "http://yourcallback.url.com",
            "mode": "subscribe",
            "topic": "orders"
          }  
    responses:
      202:

返回：202已接受

但将编码更改为x-www-form-urlencoded

/subv1form: #this doesn't work, returns 400 bad request
  post:
    description: "Subscribes to a topic"
    body:
      application/x-www-form-urlencoded:
        type: hub
        example: 
          {
            "callback": "http://yourcallback.url.com",
            "mode": "subscribe",
            "topic": "orders"
          } 
    responses:
      202:

返回400错误请求和语法错误

  {
"code": "REQUEST_VALIDATION_ERROR",
"message": "Invalid schema for content type application/x-www-form-urlencoded. Errors: Syntax error in the following text: '}: { "callback": "http://yourcallback.url.com", "mode": "subscribe",'. "
}

我发现将示例移到类型定义内无济于事-仅将错误更改为更精确的“未找到需要键[mode]”

{
"code": "REQUEST_VALIDATION_ERROR",
"message": "Invalid schema for content type application/x-www-form-urlencoded. Errors: required key [mode] not found. "
}

但是，将示例重新格式化为yaml语法确实可以，但是要求您不要在类型中指定示例。

/subv3examplereformatted: #this works
  post:
    description: "Subscribes to a topic"
    body:
      application/x-www-form-urlencoded:
        type: hub
        example: 
          id: "example1"
          callback: "http://yourcallback.com"
          mode: "subscribe"
          topic: "order"
    responses:
      202:

因此，模拟服务如何管理表单编码参数的序列化示例存在古怪之处，并且提供示例的方式也不止一种。如果您想使用x-www-form-urlencoded并提供可在模拟服务中使用的示例，则可以采用这种方法。

Raml 1.0类型与示例和mulesoft模拟服务

4 个答案:

％RAML 1.0