カスタム API ドキュメント

RAD サーバーエンジンの拡張への移動

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 +
  '    }'

カスタム API ドキュメント

目次

EndPointRequestSummary

EndPointRequestParameter

EndPointResponseDetails

EndPointObjectsYAMLDefinitions

EndPointObjectsJSONDefinitions

関連トピック

関連項目

案内メニュー

個人用ツール

名前空間

変種

表示

その他

検索

RAD Studio 11 Alexandria

RAD Studio 11 トピック

他言語版

以前のバージョン

Assistance

ツール