RAML 0.8 または 1.0 への準拠におけるよくある問題

2019 年 1 月 10 日の時点で、API エディタ (Design Center の API Designer に用意されている 2 つのエディタのうちの 1 つ) は、それ以前に作成されている RAML API 仕様プロジェクトに対してより厳しい検証をデフォルトで行います。RAML 0.8 または RAML 1.0 で書かれたパブリッシュ済みの API 仕様を API エディタで開いたときに、違反 (赤) や警告 (オレンジ色) のメッセージが表示された場合は、メッセージの内容が RAML での問題を解決するのに役立つ可能性があります。

下記は、最も一般的な問題の (MuleSoft が決めた) トップ 10 です。

少なくとも 2020 年 1 月 10 日までは猶予期間が設けられていますが、それ以降は、違反メッセージを生成する API 仕様はパブリッシュできなくなります。

使用されない URI パラメータを宣言している

API 仕様で宣言した URI パラメータが仕様内で使用されていない場合、エディタは次のメッセージを表示します。

unused uri parameter “parameter”

ベース URI パラメータとして宣言されているパラメータが使用されていない場合は、エディタは次の警告メッセージを表示します。

unused base uri parameter “parameter”

たとえば、次の API 仕様により 2 つの警告メッセージが表示されます。

unused uri parameter "unusedParam"
unused base uri parameter "unusedUriParam"
#%RAML 1.0
title: test

baseUri: http://param.raml/a/{baseUriParam1}/{nonExists}/{baseUriParam2}

baseUriParameters:
 baseUriParam1:
   type: string
 baseUriParam2:
     type: string
 unusedParam:
   type: string

/endpoint/{uriParam1}/{nonExistsUri}:
 uriParameters:
   uriParam1:
     type: string
   unusedUriParam:
     type: string

警告メッセージは、単純にこれらのパラメーターを宣言している行を削除するだけで表示されなくなります。

#%RAML 1.0
title: test

baseUri: http://param.raml/a/{baseUriParam1}/{nonExists}/{baseUriParam2}

baseUriParameters:
 baseUriParam1:
   type: string
 baseUriParam2:
     type: string

/endpoint/{uriParam1}/{nonExistsUri}:
 uriParameters:
   uriParam1:
     type: string

型名として使用されている整数が引用符で囲まれていない

整数を型名として使用し、その整数を引用符で囲まないと、エディタは違反メッセージを表示します。

expecting !!str and !!int provided

たとえば、次の仕様の型名によって違反メッセージが生成されます。

#%RAML 1.0
title: test
  types:
    400:
      type: string

問題を解決するには、400 を引用符で囲みます。

#%RAML 1.0
title: test
types:
  "400":
    type: string

次の例では、型 A の例の名前がどちらも整数であるため、違反メッセージが 2 回生成されます。

#%RAML 1.0
title: test
types:
  A:
    properties:
      a: string
      b: integer
    examples:
      1:
        a: some
        b: 16
      2:
        a: other
        b: 32

問題を解決するには、12 を引用符で囲みます。

#%RAML 1.0
title: test
types:
  A:
    properties:
      a: string
      b: integer
    examples:
      "1":
        a: some
        b: 16
      "2":
        a: other
        b: 32

例にプロパティが含まれていない

例に対象となる型のプロパティが含まれていないと、エディタは違反メッセージを表示します。

should have required property 'property name'

次の API 仕様では、age プロパティが例に含まれていません。

#%RAML 1.0
title: Example API Spec

types:
 User:
   type: object
   properties:
     firstName: string
     lastName: string
     age: integer
   example:
     firstName: John
     lastName: Smith

例にプロパティを追加するか、または型宣言でプロパティを省略可能として宣言してください。

次のケースでは、プロパティが例に追加されています。

#%RAML 1.0
title: Example API Spec

types:
 User:
   type: object
   properties:
     firstName: string
     lastName: string
     age: integer
   example:
     firstName: John
     lastName: Smith
     age: 49

次のケースでは、プロパティが省略可能として宣言されています。

#%RAML 1.0
title: Example API Spec

types:
 User:
   type: object
   properties:
     firstName: string
     lastName: string
     age?: integer
   example:
     firstName: John
     lastName: Smith

additionalProperties が false に設定されている状態で、宣言されていないプロパティが例に含まれている

型の例に型宣言で記述されていない 1 つまたは複数のプロパティが含まれていると、エディタは次のメッセージを表示します。

should NOT have additional properties

たとえば、次の API 仕様に対してエディタはこのメッセージを表示します。

#%RAML 1.0
title: Example API Spec

types:
 User:
   type: object
   additionalProperties: false
   properties:
     firstName: string
     lastName: string
   example:
     firstName: John
     lastName: Smith
     age: 49

この問題の解決法は 3 つあります。

  • 例から余分なプロパティを削除する

    #%RAML 1.0
    title: Example API Spec
    
    types:
     User:
       type: object
       additionalProperties: false
       properties:
         firstName: string
         lastName: string
       example:
         firstName: John
         lastName: Smith
  • 型宣言にプロパティを追加する

    #%RAML 1.0
    title: Example API Spec
    
    types:
     User:
       type: object
       additionalProperties: false
       properties:
         firstName: string
         lastName: string
         age: integer
       example:
         firstName: John
         lastName: Smith
         age: 49
  • additionalProperties の値を true に変更するか、または additionalProperties の行を削除する (additionalProperties はデフォルトで true であるため)

    #%RAML 1.0
    title: Example API Spec
    
    types:
     User:
       type: object
       properties:
         firstName: string
         lastName: string
       additionalProperties: true
       example:
         firstName: John
         lastName: Smith
         age: 49

ペイロードのメディア種別を宣言していない

ペイロードの宣言でメディア種別が宣言されていないと、エディタは次のメッセージを表示します。

Payload media type is mandatory

たとえば、次の API 仕様に対してエディタはこのメッセージを表示します。

#%RAML 1.0
title: Example API Spec
/media:
 get:
   responses:
     200:
       body:
         type: string

この問題の解決法は 2 つあります。

  • ペイロード宣言でメディア種別をローカルに宣言する

    #%RAML 1.0
    title: Example API Spec
    /media:
     get:
       responses:
         200:
           body:
            application/json:
             type: string
  • API 仕様でデフォルトのメディア種別をグローバルに指定する

    #%RAML 1.0
    title: Example API Spec
    
    mediaType: application/json
    
    /media:
     get:
       responses:
         200:
           body:
             type: string

次の例では、グローバル宣言とローカル宣言の両方を使用しています。このケースでは、mediaType ノードは application/jsonapplication/xml を受け入れ可能なメディア種別として定義しています。最初の種別である Person は、どちらのメディア種別であっても構わずに本文を返します。2 番目の種別である Another は、ローカル宣言でグローバル宣言を上書きし、JSON の本文のみを返します。

#%RAML 1.0
title: New API
mediaType: [ application/json, application/xml ]
types:
  Person:
  Another:
/list:
  get:
    responses:
      200:
        body: Person[]
/send:
  post:
    body:
      application/json:
        type: Another

!include タグを使用してフラグメントを参照していない

API 仕様で uses キーを使用してフラグメントを参照していると、エディタは次のメッセージを表示します。

Fragments must be imported by using '!include'

uses キーを使用してライブラリを適用していない

API 仕様で !include タグを使用してライブラリを適用していると、エディタは次のメッセージを表示します。

Libraries must be applied by using 'uses'

無効な JSON を含むスキーマが含まれている

schemas プロパティの値に含まれるファイルには、有効な JSON が必要です。

最初の例には appSwitcher.json というスキーマが含まれています。しかし、2 番目の例では、JSON にエラーがあり、最後の値の末尾が引用符であるべきところがカンマになっています。

#%RAML 0.8
title: ExampleRAML
schemas:
  - appSwitcher: !include schemas/appSwitcher.json
{
  "appMenuItems" : [
    {
      "type" : "Tabset" ,
      "content" : null ,
      "icons" : null ,
      "colors" : null ,
      "label" : "Call Center" ,
      "url" : "/home/home.jsp?tsid=02uxx00000056Sr"
    } , {
      "type" : "Tabset" ,
      "content" : null ,
      "icons" : null ,
      "colors" : null ,
      "label" : "Community" ,
      "url" : "/home/home.jsp?tsid=02uxx00000056Sw"
    } , {
      "type" : "Tabset" ,
      "content" : null ,
      "icons" : null ,
      "colors" : null ,
      "label" : "App Launcher" ,
      "url" : "/app/mgmt/applauncher/appLauncher.apexp?tsid=02uxx00000056Sx,
    }
  ]
}

JSON スキーマの例で無効な JSON を使用している

次の API 仕様では JSON スキーマの例が間違っていますが、有効な JSON を使用しなければなりません。

#%RAML 0.8
title: ExampleRAML
...
/api:
  get:
    responses:
      200:
        body:
          application/json:
            schema:
              {
                "type": "object",
                "required": true,
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                  "a": {
                    "type": "boolean",
                    "required": true
                  }
                }
              }
            example:
              {
                "a: {
                  "a": ""
                }

応答例に無効な JSON が含まれている

応答メッセージの例として JSON ファイルが含まれている場合、ファイルの JSON は有効でなければなりません。次の違反のケースでは、応答コード 200 の応答例に !include ステートメントが含まれています。また、含まれているファイルの JSON では、最後のキー/値ペアの最後にカンマがあります。

#%RAML 1.0
title: ExampleRAML
...
/resume:
  description: "Gets candidate's resume."
  get:
    queryParameters:
       ...
    headers:
      ...
    responses:
      200:
        body:
          application/json:
            example: !include exampleResumeData-200.json
      500:
        ...
{
...
"assesments.characteristic.focusofattention.data"= "",
}

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub