如何包含对 raml 资源的常见响应

Posted

技术标签:

【中文标题】如何包含对 raml 资源的常见响应【英文标题】:how to include common responses to raml resource 【发布时间】:2016-10-24 17:55:57 【问题描述】:

我有 raml 文档,并尝试将新的 API 文档添加到该文档中。

我浏览了基本的 RAML 文档。

我有 raml 文件。

#Filename: base.raml
title: Test RAML
documentation:
  - title: Test RAML docs first time :)
    content: This is RAML testing
baseUri: https://myportal.com/version/scriptmanagement
version: v1.0
mediaType: application/json
protocols: [ HTTPS ]

/test:
    !include raml/test.raml

而实际的raml内容在test.raml

#Filename: test.raml
displayName: Test RAML Inheritance
description: Testing for RAML inheritance for responses.

get:
    description: Get all TEST
    headers:
        name:
            description: name required in each request
            example: testname
            required: true
    responses:
        200:
            description: SUCCESS
            body:
                application/json:
                    example: |
                        
        400:
            description: BAD REQUEST
            body:
                application/json:
                    example: |
                        "error": "Bad Request"
        500:
            description: INTERNAL ERROR
            body:
                application/json:
                    example: |
                        "error": "Internal Error"

post:
    description: Get all TEST
    headers:
        name:
            description: name required in each request
            example: testname
            required: true
    responses:
        200:
            description: SUCCESS
            body:
                application/json:
                    example: |
                        "message": "Created"
        400:
            description: BAD REQUEST
            body:
                application/json:
                    example: |
                       "error": "Bad Request"
        500:
            description: INTERNAL ERROR
            body:
                application/json:
                    example: |
                        "error": "Internal Error"


/test_id:
    description: TEST DETAILS
    get:
        description: Retrieve resource own by x-user-name
        headers:
            name:
                description: name required in each request
                example: testname
                required: true
        responses:
            200:
                description: SUCCESS
                body:
                    application/json:
                        example: |
                            "message": "Details"
            400:
                description: BAD REQUEST
                body:
                    application/json:
                        example: |
                            "error": "Bad Request"
            500:
                description: INTERNAL ERROR
                body:
                    application/json:
                        example: |
                            "error": "Internal Error"

在上面的 RAML 中,400500 响应很常见,name 标头很常见。

如何编写一次并添加到所有资源中?我试过traits<<: 都不起作用。

【问题讨论】:

特质对我有用!!! @Sachin 你能给出你的trait 例子吗? @Sachin 请在此处分享您的示例。为问题添加新答案 【参考方案1】:

特征在这里是正确的解决方案。这是您的 name 标头场景的示例:

定义特征

traits:
  nameHeader:
    headers:
      name:
        description: name required in each request
        example: testname
        required: true

使用特征

要使用此特征,您必须在请求规范中明确提及:

/test_id:
  description: TEST DETAILS
  get:
    description: Retrieve resource own by x-user-name
    is: [nameHeader]
    responses:
      200:
        description: SUCCESS
        body:
          application/json:
            example: |
              "message": "Details"

您可以使用相同的方式为响应定义特征。

【讨论】:

我从未尝试过traits,但如果可行,我会尝试选择这个。 谢谢!很高兴我能在将近一年后提供帮助:) 嗨@Nilesh,我是新手。请以 400 个响应特征的示例完成您的答案 @mohammadjawadBarati 我不是在处理 RAML,我们将文档从 RAML 更改为 swagger。

以上是关于如何包含对 raml 资源的常见响应的主要内容,如果未能解决你的问题,请参考以下文章

Dropwizard + Raml -> 空资源

raml 语法 - 嵌套 API 资源名称 - 大括号的使用

RAML 默认信封

RAML:在资源中引用 uriParameters

是从体型(RAML)中排除属性的方法吗?

RAML - 如何设计带有参数的端点?