カスタム 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 +
' }'