Swagger ドキュメントの生成

概要

Swagger は、RESTful API の記述およびドキュメント化に使用されるプロジェクト仕様です。ColdFusion 12 では、REST CFC を実装してサーバーに登録した後、その REST CFC から自動的に Swagger ドキュメントを作成できます。ColdFusion でサポートされる Swagger のバージョンは 1.2 です。 

Swagger プロジェクト概要について詳しくは、Swagger のドキュメントを参照してください。Swagger 1.2 の仕様はこちらから参照できます。

ドキュメント生成プロセス

Swagger ドキュメント生成機能は ColdFusion サーバーに搭載されています。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>

新しい responseMessages 属性の使用

ColdFusion 12 リリースでは、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 ドキュメントは以下のようになります。

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

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

  1. システム内の REST CFC が配置されるルートパスを入力します。または、「サーバーをブラウズ」をクリックし、CFC アプリケーションが存在するパスを選択することもできます。

  2. REST サービスのホスト名を入力します。例:localhost:8500

  3. サービスマッピング」の文字列の名前を入力します。例:http://localhost/rest/{service mapping}/test

  4. Web サービスを呼び出す際にこのアプリケーションをデフォルトとして設定する場合は、該当するチェックボックスをオンにします。

Swagger API ドキュメントへのアクセス

Swagger の API 表現には、次の 2 つのファイルタイプが含まれます。

  1. リソースリスト - 一般的な API 情報が含まれ、リソースのリストが示されたルートドキュメントです。各リソースには、そのリソースに対する API 操作を定義した独自の URL があります。
  2. 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"
                }
            }
        }
    }
}

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 タイプのリスト。すべての API に適用されるグローバルな設定ですが、個別の API 呼び出しでオーバーライドすることもできます。

Cfcomponent.consumes

produces

[string]

このリソース上の API が生成できる 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 フィールドを使用する必要があります。

Operation Object は、操作が値を返さないことを示す void という値を 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

 

ヘルプをすばやく簡単に入手

新規ユーザーの場合