表示: Delphi C++
表示設定

カスタム API ドキュメント

提供: RAD Studio
移動: 案内, 検索

EMS サーバーの拡張 への移動


RAD Studio では、新規作成した EMS リソース モジュールの API ドキュメントを YAML 形式および JSON 形式で作成することができます。この新しい実装は、Swagger RESTful API ドキュメント仕様に基づいています。

EMS.ResourceType には、リソースのエンドポイントに関する API ドキュメントの生成に使用できる新しい属性が実装されています。

EndPointRequestSummary

メソッドの説明です。

[EndPointRequestSummary('ATags', 'ASummary', 'ADescription', 'AProduces', 'AConsume')]
  • Tags: タグを定義します。
  • Summary: メソッド タイトル。
  • Description: メソッドの説明。
  • Produces: この API で生成できる MIME タイプ。これはすべての API に共通の指定ですが、個々の API 呼び出しでオーバーライドすることができます。この値は Mime Types に記述されたものでなければなりません。
  • Consume: この API で受け付けられる MIME タイプ。これはすべての API に共通の指定ですが、個々の API 呼び出しでオーバーライドすることができます。この値は Mime Types に記述されたものでなければなりません。

エンドポイントの GET メソッドの説明の宣言例:

[EndPointRequestSummary('Api Doc', 'Get API EndPoints', 'Used to retrieve all the API EndPoints', 'application/json', '')]
procedure Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);

EndPointRequestParameter

要求内で使用されるパラメータの説明です。

名前と場所の組み合わせでパラメータが一意に定義されます。

パラメータの種類には、Path、Query、Header、Body、Form の 5 つがあります。

[EndPointRequestParameter('AIn', 'AName', 'ADescription', 'ARequired', 'AType', 'AFormat', 'AItemType', 'AJSONSchema', 'AReference')]
  • ParamIn: パラメータの場所。Path、Query、Header、Body、Form のいずれかです。
  • Name: パラメータの名前。パラメータ名では大文字と小文字が区別されます。
    • パラメータの場所が 'Body' の場合、この名前は 'body' でなければなりません。
    • パラメータの場所が 'Path' の場合、この名前は、Paths オブジェクトのパス フィールドの中の、関連するパス セグメントに一致する名前でなければなりません。
    • それ以外の場合、この名前は ParamIn に一致します。
  • Description: パラメータの簡単な説明。使用例を含むことができます。GFM 構文のリッチ テキスト表現を使用できます。
  • Required: このパラメータが必須かどうかを示します。パラメータが 'Path' の場合、このプロパティは必須で、値は True でなければなりません。それ以外の場合は任意で、デフォルト値は False です。
  • ParamType: パラメータの種類。値が 'Body' 以外の場合、この値は 'spArray'、'spBoolean'、'spInteger'、'spNumber'、'spNull'、'spObject'、'spString'、'spFile' のいずれかでなければなりません。ParamType が 'spFile' の場合、受け付ける MIME タイプは "multipart/form-data" または "application/x-www-form-urlencoded" で、パラメータは "form-data" でなければなりません。値が 'Body' の場合、JSONSchema および Reference を指定する必要があります。
  • ItemFormat: ParamType の拡張形式。'None'、'Int32'、'Int64'、'Float'、'Double'、'Byte'、'Date'、'DateTime'、または 'Password'。
  • ItemType: ParamType が 'array' の場合に必須。配列内の項目の型を記述します。
  • JSONSchema: サーバーに送信されるプリミティブのスキーマ定義。本体の要求構造の定義です。ParamType が 'Array' または 'Object' の場合にスキーマを定義できます。
    • 例:
      JSON 形式の場合: {"type": "object","additionalProperties": {"type": "string"}}
      YAML 形式の場合:
      type: object
      additionalProperties:
      type: string
  • Reference: サーバーに送信されるプリミティブのスキーマ定義。本体の要求構造の定義です。種類が 'Array' または 'Object' の場合にスキーマを定義できます。
    • 例:
      '#/definitions/pet'
[EndPointRequestParameter(TAPIDocParameter.TParameterIn.Path, 'item', 'Path Parameter item Description', true, TAPIDoc.TPrimitiveType.spString, TAPIDoc.TPrimitiveFormat.None, TAPIDoc.TPrimitiveType.spString, '', '')]

EndPointResponseDetails

要求応答の説明です。

[EndPointResponseDetails('ACode', 'ADescription', 'AType', 'AFormat', 'ASchema', 'AReference')]
  • Code: 応答コード。
  • Description: 応答コードの説明。
  • PrimitiveType: 返されるプリミティブの型。Swagger 仕様のプリミティブ データ型は、JSON-Schema Draft 4 でサポートされる型が基になっています。JSON スキーマには、JSON 値のプリミティブ型として 'spArray'、'spBoolean'、'spInteger'、'spNumber'、'spNull'、'spObject'、'spString' の 7 つが定義されています。「JSON Schema primitive types(JSON スキーマのプリミティブ型)」を参照してください。パラメータ オブジェクトや応答オブジェクトでは、もう 1 つ 'spFile' というプリミティブ データ型が使われます。これは、パラメータ型や応答をファイルとして設定するためのものです。
  • PrimitiveFormat: 返されるプリミティブの形式。'None'、'Int32'、'Int64'、'Float'、'Double'、'Byte'、'Date'、'DateTime'、'Password' など。
  • Schema
    • 例:
      JSON 形式の場合: {"type": "object","additionalProperties": {"type": "string"}}
      YAML 形式の場合:
      type: object
      additionalProperties:
      type: string
  • Reference: 返されるプリミティブのスキーマ定義。応答構造の定義です。PrimitiveType が 'spArray' または 'spObject' の場合にスキーマ定義を指定できます。
    • 例:
      '#/definitions/pet'
[EndPointResponseDetails(200, 'Ok', TAPIDoc.TPrimitiveType.spObject, TAPIDoc.TPrimitiveFormat.None, '', '#/definitions/EmployeeTable')]
[EndPointResponseDetails(404, 'Not Found', TAPIDoc.TPrimitiveType.spNull, TAPIDoc.TPrimitiveFormat.None, '', '')]

EndPointObjectsYAMLDefinitions

API YAML 版のオブジェクトの定義です。

  [EndPointObjectsYAMLDefinitions(Objects)]
  • Objects: YAML 形式のオブジェクト定義。
type
  [ResourceName('SampleAttributes')]
  [EndPointObjectsYAMLDefinitions(cYamlDefinitions)]
 
// YAML Object definition:
  cYamlDefinitions =
  '# ' +  sLineBreak +
  ' PutObject:' +  sLineBreak +
  '   properties:' +  sLineBreak +
  '    EMP_NO:' +  sLineBreak +
  '     type: integer' +  sLineBreak +
  '    FIRST_NAME:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    LAST_NAME:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    PHONE_EXT:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    HIRE_DATE:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '     format: date-time' +  sLineBreak +
  '    DEPT_NO:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    JOB_CODE:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    JOB_GRADE:' +  sLineBreak +
  '     type: integer' +  sLineBreak +
  '    JOB_COUNTRY:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '    SALARY:' +  sLineBreak +
  '     type: integer' +  sLineBreak +
  '    FULL_NAME:' +  sLineBreak +
  '     type: string' +  sLineBreak +
  '# '

EndPointObjectsJSONDefinitions

API JSON 版のオブジェクトの定義です。

    [EndPointObjectsJSONDefinitions(Objects)]
  • Objects: JSON 形式のオブジェクト定義。
type
  [ResourceName('SampleAttributes')]
  [EndPointObjectsJSONDefinitions(cJSONDefinitions)]
 
// JSON Object definition:
 
cJSONDefinitions =
 '{' +  sLineBreak +
  '   "PutObject": {' +  sLineBreak +
  '       "properties": {' +  sLineBreak +
  '           "EMP_NO": {' +  sLineBreak +
  '               "type": "integer"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "FIRST_NAME": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "LAST_NAME": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "PHONE_EXT": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "HIRE_DATE": {' +  sLineBreak +
  '               "type": "string",' +  sLineBreak +
  '               "format": "date-time"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "DEPT_NO": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "JOB_CODE": {' +  sLineBreak +
  '               "type": "string"' +  sLineBreak +
  '           },' +  sLineBreak +
  '           "JOB_GRADE": {' +  sLineBreak +
  '               "type": "integer"' +  sLineBreak +
  '           },' +  sLineBreak +
  '            "JOB_COUNTRY": {' +  sLineBreak +
  '                "type": "string"' +  sLineBreak +
  '            },' +  sLineBreak +
  '            "SALARY": {' +  sLineBreak +
  '                "type": "integer"' +  sLineBreak +
  '            },' +  sLineBreak +
  '            "FULL_NAME": {' +  sLineBreak +
  '                "type": "string"' +  sLineBreak +
  '            }' +  sLineBreak +
  '        }' +  sLineBreak +
  '    }'

関連トピック

関連項目

個人用ツール
他言語版
以前のバージョン
Assistance