概要

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"/> 
            <!--- Adding the student to data base. ---> 
    </cffunction> 
    <cffunction name="addStudents" access="remote" returntype="void" httpmethod="POST" description="add students"> 
        <cfargument name="name" type="student[]" required="yes" restargsource="body"/>        
            <!--- Adding the student to data base. ---> 
    </cffunction>
	<cffunction name="deleteStudent1" access="remote" returntype="void" httpmethod="DELETE" description="delete students"> 
        <cfargument name="students" type="student[]" required="yes" restargsource="Body"/> 
            <!--- Adding the student to data base. ---> 
    </cffunction>
    <cffunction name="updateStudentAddress" access="remote" returntype="address" httpmethod="POST" restpath="{studentId}" description="modify student address" hint="modify the address for given studentId"> 
        <cfargument name="studentId" type="numeric" required="yes" restargsource="PATH" /> 
        <cfargument name="address" type="address" required="yes" restargsource="Body" >
            <!--- Adding the student to data base. ---> 
    </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"/> 
            <!--- Create a student object and return the object. This object will handle the request now. ---> 
        <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="this is title">
	<cfset this.restsettings.restDocInfo.apiVersion="2.0">
	<cfset this.restsettings.restDocInfo.description="this is description">
	<cfset this.restsettings.restDocInfo.termOfServiceUrl="url is here">
	<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" >
	<!--- Test with various 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="Hello " & name>
		<cfreturn res>
	</cffunction>	
</cfcomponent>	

このサンプルの responseMessages コードから生成された Swagger API ドキュメントは以下のようになります。 

response-messages

CFC アプリケーションの登録

ColdFusion Administrator を起動します。左側のパネルで、データとサービス/REST サービスをクリックし、次に表示されるダイアログの説明に従って設定値を追加します。

rest-services
  1. システム内の REST CFC が配置されるルートパスを入力します。または、「サーバーをブラウズ」をクリックし、CFC アプリケーションが存在するパスを選択することもできます。
  2. REST サービスのホスト名を入力します。例:localhost:8500 
  3. サービスマッピング」の文字列の名前を入力します。例:http://localhost/rest/{service mapping}/test 
  4. 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 ディスカバリサーバー設定」をクリックします。次のサンプルスナップショットに示すように、設定値を追加します。 

CF Discovery Server Configuration

API のインポート

API Manager ポータルを起動します。「新規 API を作成」をクリックし、「ColdFusion から REST API をインポート」をクリックします。

API List-Import REST API from CF

CFC と Swagger のマッピング構造

CFC フィールドタイプと Swagger フィールドタイプを次のマッピング構造により比較できます。 

リソースリストスキーマ

リソースリストは、API 記述のルートドキュメントとして機能します。リソースリストには、API および使用可能なリソースのインベントリに関する一般的な情報が含まれます。

Swagger ドキュメントのフィールド名

タイプ

説明

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 個以上の操作を格納します。

詳細:Operation Object

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"、
"OPTIONS"。値は大文字である必要があります。

Cffunction.httpmethod

nickname

String

必須。後で操作しやすくするための出力読み取り用ツールで使用できる操作の一意の ID。

Cffunction.name

notes

String

操作の振る舞いに関する詳しい説明。

Cffunction.hint

parameters

[Parameter Object]

必須。操作の入力。パラメーターが不要な場合は、空の配列を指定する必要があります。

詳細: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  

本作品は Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License によってライセンス許可を受けています。  Twitter™ および Facebook の投稿には、Creative Commons の規約内容は適用されません。

法律上の注意   |   プライバシーポリシー