针对raml的一些使用技巧和raml-jaxrs-maven-plugin插件的使用注意

最新推荐文章于 2021-06-27 11:16:10 发布

原创最新推荐文章于 2021-06-27 11:16:10 发布 · 1.2k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#raml #maven #插件 #schema

API设计专栏收录该内容

5 篇文章

订阅专栏

本文介绍了raml-jaxrs-maven-plugin插件，它将RAML文件转化为Java代码，但不支持RAML 1.0和某些特性如Examples、JSON Schema生成。同时，分享了RAML的语法技巧，包括&和*的使用以及如何在0.8版中引用其他类型对象。

raml-jaxrs-maven-plugin是一种将raml文件转换为java代码的maven插件

该插件有以下几点注意事项：

目前为止并不支持 raml 1.0 的解析
不支持Examples,JSON schema的生成，这里的不支持schema生成指的是生成request代码中，并不会同样生成返回的schema的代码，但是会在model目录下生成schema实体
不支持外部Trait 和 Resource-Type raml资源的解析
可以外部定义schemas

raml的一些额外语法技巧

(1). & 和 *的用法

resourceTypes:
  - base:
      get?:
        responses: &standardResponses
          200:
            description: OK
            body:
              application/json:
                example:
      put?:
        responses: *standardResponses
      patch?:
        responses: *standardResponses
      post?:
          responses:
            201:
              description: Created
      delete?:
        responses: *standardResponses

&{name} - declare a block *{name} - use the block
如上片段：
在responses用 & 进行声明standardResponses
在下面的responses用 * 进行standardResponses所标识的responses的引用

(2). raml 0.8 中引入其他类型对象

- author: |
      {
            "properties": {
                "name": {
                    "type": "string"
                },
                "email": {
                    "type": "string"
                },
                "date": {
                    "description": "ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ",
                    "type": "string"
                }
            },
            "type": "object"
        }
  - authors_info: |
      {  "$schema": "http://json-schema.org/draft-03/schema",
         "type": "object",
         "description": "A collection of product Presentations",
         "properties": {
           "authors": {
              "type": "array",
              "items": { "$ ref": "author" }

         }
         }
      }

raml中可以通过”$ref”的方式来引用其他schema类型，也可以以同样方式进行非数组引用：

 - authors_info: |
          {  "$schema": "http://json-schema.org/draft-03/schema",
             "type": "object",
             "description": "A collection of product Presentations",
             "properties": {
               "authors": {
                  "$ref": "author" 
             }
             }
          }

将schema拆分后直接引用schema在raml中映射的名称，也可以达到目的