Swagger ドキュメントのフィールド名
最終更新日 :
2022年1月19日
概要
Swagger は、RESTful API の記述およびドキュメント化に使用されるプロジェクト仕様です。Adobe ColdFusion（2016 リリース）では、REST CFC を実装してサーバーに登録した後、その REST CFC から自動的に Swagger ドキュメントを作成できます。ColdFusion でサポートされる Swagger のバージョンは 1.2 です。
Swagger プロジェクト概要について詳しくは、Swagger のドキュメントを参照してください。Swagger 1.2 の仕様はこちらから参照できます。
ドキュメント生成プロセス
Swagger ドキュメント生成機能は ColdFusion Server に搭載されています。ColdFusion サーバーは、REST CFC アプリケーションの登録後、Swagger ドキュメントを自動的に生成します。
REST CFC ファイルの作成
任意の REST CFC アプリケーションファイルを作成し、このファイルを ColdFusion サーバーのルートフォルダー（wwwroot）に配置します。次の studentservice.cfc ファイルに、CFC ファイル内容の構造のサンプルを示します。
<cfcomponent rest="true" restpath="studentService">
<cffunction name="addStudent" access="remote" returntype="void" httpmethod="PUT" description="add student">
<cfargument name="name" type="string" required="yes" restargsource="Form"/>
<cfargument name="age" type="numeric" required="yes" restargsource="Form"/>
<!---データベースに構造体を追加。--->
</cffunction>
<cffunction name="addStudents" access="remote" returntype="void" httpmethod="POST" description="add students">
<cfargument name="name" type="student[]" required="yes" restargsource="body"/>
<!---データベースに構造体を追加。--->
</cffunction>
<cffunction name="deleteStudent1" access="remote" returntype="void" httpmethod="DELETE" description="delete students">
<cfargument name="students" type="student[]" required="yes" restargsource="Body"/>
<!---データベースに構造体を追加。--->
</cffunction>
<cffunction name="updateStudentAddress" access="remote" returntype="address" httpmethod="POST" restpath="{studentId}" description="学生のアドレスを修正意" hint="studentId のアドレスを修正">
<cfargument name="studentId" type="numeric" required="yes" restargsource="PATH" />
<cfargument name="address" type="address" required="yes" restargsource="Body" >
<! ---データベースに構造体を追加。--->
</cffunction>
<cffunction name="getStudent" access="remote" returntype="Student" restpath="{name}-{age}" httpmethod="GET" description="retrieve student" produces="application/json" responseMessages="404:Not found,200:Successfull:student" >
<cfargument name="name" type="string" required="yes" restargsource="Path"/>
<cfargument name="age" type="string" required="yes" restargsource="Path"/>
<!---学生オブジェクトを作成してそのオブジェクトを返します。このオブジェクトは、ここでリクエストを処理します。--->
<cfset myobj = CreateObject("component", "Student")>
<cfset myobj.name = name>
<cfset myobj.age = age>
<cfreturn myobj>
</cffunction>
</cfcomponent>
application.cfc ファイルの使用
ColdFusion サーバーが Swagger ドキュメントを自動的に生成しないようにする場合、application.cfc ファイル内の次のコードを false に設定します。CF Administrator で、登録済みのアプリケーションを更新します。
<cfset this.restsettings.generateRestDoc="false">
参考までに、サンプルの application.cfc ファイルを以下に示します。
<cfcomponent>
<cfset this.name="info" />
<cfset this.sessionmanagement = true />
<cfset this.restsettings.generateRestDoc="true">
<cfset this.restsettings.restDocInfo.title="これはタイトルです">
<cfset this.restsettings.restDocInfo.apiVersion="2.0">
<cfset this.restsettings.restDocInfo.description="これは説明です">
<cfset this.restsettings.restDocInfo.termOfServiceUrl="url はこちら">
<cfset this.restsettings.restDocInfo.contact="xyz@adobe.com">
<cfset this.restsettings.restDocInfo.license="adobe 1.0">
<cfset this.restsettings.restDocInfo.licenseUrl="http://abc.com">
</cfcomponent>
新しいレスポンスメッセージ属性の使用
Adobe ColdFusion（2016 リリース）では、responseMessages という新しい属性が導入されました。この属性は、REST CFC ファイル内で以下のサンプルファイルのように使用できます。
<cfcomponent rest="true" restPath="/cookieService" produces="text/plain" > <!---さまざまな produces でテスト ---> <cffunction name="sayPlainHelloUser" responseMessages="404:Not Found,200:successful,10:notdefine" access="remote" returnType="String" httpMethod="GET" produces="text/plain"> <cfargument name="nAme" type="string" restargsource="cOOkie" required="false" default="CF"> <cfset res="こんにちは。" & name> <cfreturn res> </cffunction> </cfcomponent>
このサンプルの responseMessages コードから生成された Swagger API ドキュメントは以下のようになります。
CFC アプリケーションの登録
ColdFusion Administrator を起動します。左側のパネルで、データとサービス／REST サービスをクリックし、次に表示されるダイアログの説明に従って設定値を追加します。
- システム内の REST CFC が配置されるルートパスを入力します。または、「サーバーをブラウズ」をクリックし、CFC アプリケーションが存在するパスを選択することもできます。
- REST サービスのホスト名を入力します。例：localhost:8500
- 「サービスマッピング」の文字列の名前を入力します。例：http://localhost/rest/{service mapping}/test
- Web サービスを呼び出す際にこのアプリケーションをデフォルトとして設定する場合は、該当するチェックボックスをオンにします。
Swagger api-docs へのアクセス
Swagger の API 表現は、次の 2 つのファイルタイプで構成されます。
リソースリスト - 一般的な API 情報が含まれ、リソースのリストが示されたルートドキュメントです。各リソースには、そのリソースに対する API 操作を定義した独自の URL があります。
API 宣言 - API 呼び出しとモデルを含む、リソースについて記述するドキュメントです。
ColdFusion により生成された Swagger API ドキュメントを確認するには、次のように ColdFusion サーバーのパスを使用します。
<ColdFusion server URL path:port number>/<Service Mapping name>/api-docs/<resourcePath name>
リソースリストには、このパスから resourcePath name を除いて使用することでアクセスできます（<ColdFusion server URL path:port number>/Service Mapping name>/api-docs）。
Service Mapping name は、ColdFusion サーバーに REST アプリケーションを登録する際に指定する名前です。
例：localhost:8500/test/api-docs/studentService
サンプルの studentservice.cfc REST CFC ファイルから生成された Swagger API ドキュメントは、次の API ドキュメントのようになります。
{
"swaggerVersion":"1.2",
"apiVersion":"1.0",
"basePath":"localhost:8500/rest/test",
"resourcePath":"/studentService",
"apis":[
{
"path":"/studentService/",
"description":"",
"operations":[
{
"nickname":"addStudents",
"method":"POST",
"summary":"add students",
"type":"void",
"parameters":[
{
"name":"name",
"paramType":"body",
"allowMultiple":false,
"required":true,
"type":"array",
"items":{
"$ref":"student"
}
}
]
},
{
"nickname":"deleteStudent1",
"method":"DELETE",
"summary":"delete students",
"type":"void",
"parameters":[
{
"name":"students",
"paramType":"body",
"allowMultiple":false,
"required":true,
"type":"array",
"items":{
"$ref":"student"
}
}
]
},
{
"nickname":"addStudent",
"method":"PUT",
"summary":"add student",
"type":"void",
"parameters":[
{
"name":"name",
"paramType":"form",
"allowMultiple":false,
"required":true,
"type":"string"
},
{
"name":"age",
"paramType":"form",
"allowMultiple":false,
"required":true,
"type":"number"
}
]
}
]
},
{
"path":"/studentService/{name}-{age}",
"description":"",
"operations":[
{
"nickname":"getStudent",
"method":"GET",
"summary":"retrieve student",
"type":"student",
"produces":[
"application/json"
],
"parameters":[
{
"name":"name",
"paramType":"path",
"allowMultiple":false,
"required":true,
"type":"string"
},
{
"name":"age",
"paramType":"path",
"allowMultiple":false,
"required":true,
"type":"string"
}
],
"responseMessages":[
{
"code":404,
"message":"Not found"
},
{
"code":200,
"message":"Successfull",
"responseModel":"student"
}
]
}
]
},
{
"path":"/studentService/{studentId}",
"description":"",
"operations":[
{
"nickname":"updateStudentAddress",
"method":"POST",
"summary":"modify student address",
"notes":"modify the address for given studentId",
"type":"address",
"parameters":[
{
"name":"studentId",
"paramType":"path",
"allowMultiple":false,
"required":true,
"type":"number"
},
{
"name":"address",
"paramType":"body",
"allowMultiple":false,
"required":true,
"type":"address"
}
]
}
]
}
],
"models":{
"address":{
"id":"address",
"description":"this is a address component",
"required":[
],
"properties":{
"country":{
"type":"string"
},
"street":{
"type":"string"
},
"houseNo":{
"type":"number",
"format":"double"
},
"state":{
"type":"string"
}
}
},
"student":{
"id":"student",
"description":"this is a student component",
"required":[
"address",
"name",
"age"
],
"properties":{
"address":{
"$ref":"IndiaAddress"
},
"name":{
"type":"string"
},
"age":{
"type":"number",
"format":"double"
}
}
},
"IndiaAddress":{
"id":"IndiaAddress",
"description":"India address fromat",
"required":[
],
"properties":{
"country":{
"type":"string"
},
"pin":{
"type":"number",
"format":"double"
},
"street":{
"type":"string"
},
"district":{
"type":"string"
},
"houseNo":{
"type":"number",
"format":"double"
},
"state":{
"type":"string"
}
}
}
}
}
CF REST サービスからの API のインポート
パブリッシャーは、API 作成中に CF REST API サービスをインポートすることができます。このオプションを選択する前に、API Manager で CF サーバーを追加してください。
注意：
API Manager にリモートでアクセスする場合にのみ、CF サーバーを追加します。
API Manager は、システム内の ColdFusion 上にインストールできます。API Manager は cfusion /ApiManager パスでインストールされます。詳しくは、ColdFusion と API Manager の統合機能を参照してください。
API Manager での CF サーバーの追加
API Manager を管理者モードで開始します。左側のパネルの「CF ディスカバリサーバー設定」をクリックします。次のサンプルスナップショットに示すように、設定値を追加します。
API のインポート
API Manager ポータルを起動します。「新規 API を作成」をクリックし、「ColdFusion から REST API をインポート」をクリックします。
CFC と Swagger のマッピング構造
CFC フィールドタイプと Swagger フィールドタイプを次のマッピング構造により比較できます。
リソースリストスキーマ
リソースリストは、API 記述のルートドキュメントとして機能します。リソースリストには、API および使用可能なリソースのインベントリに関する一般的な情報が含まれます。
|
|
タイプ |
説明 |
CF フィールド |
|
SwaggerVersion |
String |
必須。使用している Swagger 仕様のバージョンを指定します。 |
API Manager を使用してプログラムにより更新 |
|
apis |
Resource Object |
必須。仕様のリソースをリストします。この配列には 0 個以上の要素を格納できます。 |
N/A |
|
apiVersion |
string |
アプリケーション API のバージョンを示します。 |
application.cfc ファイルを使用して変更 |
|
info |
Info Object |
API に関するメタデータを示します。クライアントはこのメタデータを使用でき、Swagger UI で参考情報として表示できます。 |
application.cfc ファイルを使用して変更 |
|
authorizations |
Authorizations Object |
この API で許可される認証スキームに関する情報を示します。 認証スキームのタイプ。"basicAuth"、"apiKey"、"oauth2" のいずれかの値である必要があります。 |
API Manager を使用してプログラムにより更新
|
API 宣言スキーマ
API 宣言では、リソース上で公開される API に関する情報を示します。リソースごとに 1 ファイルを指定します。path フィールドに記述された URL にファイルを保存します。
|
Swagger ドキュメントのフィールド名 |
タイプ |
説明 |
CF フィールド |
|
basePath |
string |
必須。API を配信するルート URL。 |
CFC の解析時にプログラムにより追加 |
|
consumes |
[string] |
このリソース上の API が使用できる MIME タイプのリスト。MIME タイプは、すべての API に適用されるグローバルな設定ですが、個別の API 呼び出しでオーバーライドすることもできます。 |
Cfcomponent.consumes |
|
produces |
[string] |
このリソース上の API が生成できる MIME タイプのリスト。MIME タイプは、すべての API に適用されるグローバルな設定ですが、個別の API 呼び出しでオーバーライドすることもできます。 |
Cfcomponent.produces |
|
resourcePath |
string |
この API 仕様で記述されるリソースへの basePath からの相対パス。 |
Cfcomponent.restpath |
|
apis |
[API Object] |
必須。このリソース上で公開される API のリスト。指定できる API Object は、配列内のパスあたり 1 つまでです。 |
詳細：API Object |
|
apiVersion |
string |
アプリケーション API のバージョンを示します（「仕様のバージョン」とは異なります）。 |
N/A |
|
swaggerVersion |
string |
必須。使用している Swagger 仕様のバージョンを指定します。 |
N/A |
|
authorizations |
Authorizations Object |
この API 宣言に示される操作に必要となる認証スキームのリスト。 個別の操作でこの設定をオーバーライドします。ここで複数の認証スキームを記述した場合、すべての認証スキームが適用されます。 |
プログラムにより追加（認証情報は API Manager により更新される） |
|
models |
Models Object |
このリソースで使用できるモデルのリスト。各 API 宣言ごとに個別にモデルを公開します。 |
プログラムにより生成 |
API Object スキーマ
API Object には、単一パス上の 1 つ以上の操作を記述します。apis 配列内に格納できる API Object は、パスごとに 1 つのみです。
|
Swagger ドキュメントのフィールド名 |
タイプ |
説明 |
CF フィールド |
|
description |
String |
リソースの簡潔な説明。 |
Cffunction.description |
|
operations |
[Operation Object] |
必須。このパス上で使用できる API 操作のリスト。この配列には 0 個以上の操作を格納します。 |
|
|
Path |
String |
必須。この操作で記述される操作への basePath からの相対パス。値は相対（URL）パス形式である必要があります。 |
Component.restpath + Cffunction.restpath |
Operation Object スキーマ
Operation Object では、パス上の単一の操作について記述します。operations 配列内に格納できる Operation Object は、メソッドごとに 1 つのみです。このオブジェクトには、操作の戻り値を記述するための Data Type Field が含まれています。他のモデルにリンクするには、type フィールドを使用する必要があります。
|
Swagger ドキュメントのフィールド名 |
タイプ |
説明 |
CF フィールド |
|
authorization |
Authorizations Object |
この操作を実行するために必要な認証のリスト。 |
API Manager からプログラムにより指定 |
|
consumes |
[string] |
この操作が使用できる MIME タイプのリスト。 |
Cffunction.consumes |
|
method |
String |
必須。この操作を呼び出すために必要な HTTP メソッド。次のいずれかの値である必要があります。 "GET"、"HEAD"、"POST"、"PUT"、"PATCH"、"DELETE"、 |
Cffunction.httpmethod |
|
nickname |
String |
必須。後で操作しやすくするための出力読み取り用ツールで使用できる操作の一意の ID。 |
Cffunction.name |
|
notes |
String |
操作の振る舞いに関する詳しい説明。 |
Cffunction.hint |
|
parameters |
[Parameter Object] |
必須。操作の入力。パラメーターが不要な場合は、空の配列を指定する必要があります。 |
|
|
produces |
[string] |
この操作が生成できる MIME タイプのリスト。 |
Cffunction.produces |
|
responseMessages |
[Response Message Object] |
この操作から返される可能性のあるレスポンスステータスのリスト。 |
Cfunction に導入された新しいパラメーター |
|
summary |
String |
操作の実行内容に関する簡潔な概要。 Swagger UI で最大限の可読性を確保できるように、このフィールドは 120 文字未満にしてください。 |
Cffunction.description
|
Parameter Object スキーマ
Parameter Object には、操作で送信される単一のパラメーターについて記述します。Parameter Object は、Operation Object の parameters フィールドに対応します。このオブジェクトには、このパラメーターのタイプを記述するための Data Type Field が含まれています。他のモデルにリンクするには、type フィールドを使用する必要があります。
type が File の場合、consumes フィールドが "multipart/form-data" で、paramType が "form" である必要があります。
|
Swagger ドキュメントのフィールド名 |
タイプ |
説明 |
CF フィールド |
|
allowMultiple |
boolean |
"query"、"header" または "path" パラメーターに対して複数の値を許可するための別の方法。 |
ColdFusion では使用不可 |
|
description |
string |
推奨。このパラメーターの簡潔な説明。 |
Cfargument.hint |
|
name |
string |
必須。パラメーターの一意の名前。 |
Cfargument.name |
|
paramType |
string |
必須。パラメーターのタイプ。次のいずれかの値である必要があります。"path"、"query"、"body"、"header"、"form" 注意：仕様によれば、Swagger では ColdFusion の "Cookie" および "Matrix" の paramType はサポートされません。 |
Cfargument.restargsource |
|
required |
boolean |
このパラメーターが必須かどうかを示すフラグ。 |
Cfargument.required |
CFC／Swagger／Java タイプの比較
| CFC | Swagger | Java | 追加情報 |
| string | string | string | |
| uuid | string | string | |
| guid | string | string | |
| query | カスタムモデル | coldfusion.xml.rpc.DocumentQueryBean | |
| void | void | "body" への引数マップ向け | |
| numeric | number（format double） | Double | |
| boolean | boolean | boolean | |
| date | string（format date） | java.util.Calendar | |
| any | object | java.lang.Object | |
| array | オブジェクトの配列 | java.lang.Object[] | |
| binary | バイトの配列 | byte [] | |
| struct | カスタムモデル | java.util.Map | |
| xml | string | org.w3c.dom.Documents |
