Enter the root path where REST CFCs are available in in your system. Alternatively you can click Browse Server and choose the path where the CFC application resides.
Last updated on
Apr 27, 2021
Overview
Swagger is a project specification that is used to describe and document RESTful APIs. In the 2016 release of ColdFusion, you can create swagger doc automatically from REST CFC after it is implemented and registered in server . The Swagger version that is supported in ColdFusion is 1.2.
For more information on Swagger project overview, see the Swagger documentation. Swagger specification 1.2 is available here.
Document generation process
The Swagger doc generation feature is a part of ColdFusion Server. ColdFusion server generates the Swagger doc automatically once you register REST CFC application.
Creating a REST CFC file
You can create REST CFC application file of your choice and place this file in the root folder (wwwroot) of ColdFusion server. A sample CFC file content structure is shown in the following studentservice.cfc file.
<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>
Using application.cfc file
If you do not want the ColdFusion server to generate swagger doc automatically, set the following code to false in application.cfc file. Refresh the registered application in CF administrator.
<cfset this.restsettings.generateRestDoc="false">
A sample application.cfc file is shown below for your reference.
<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>
Using new responseMessages attribute
A new attribute called responseMessages has been introduced in ColdFusion (2016 release). You can use this attribute in REST CFC file as shown in the sample file below.
<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>
The swagger API document generated from this sample responseMessages code appears as shown below.
Registering your CFC application
Start ColdFusion Administrator. Click Data & Services > REST Services on the left pane and add configuration values according to the instructions in the following dialog.
-
-
Enter the host name for the REST service. For example, localhost:8500.
-
Enter the Service Mapping string name. For example, http://localhost/rest/{service mapping}/test.
-
Select the check-box if you want to set the application as default while calling the web service.
Accessing swagger api-docs
The Swagger representation of the API contains two file types:
- The Resource Listing - This is the root document that contains general API information and lists the resources. Each resource has its own URL that defines the API operations on it.
- The API Declaration - This document describes a resource, including its API calls and models.
You can verify the ColdFusion generated swagger APIs document by using the ColdFusion server path as follows:
<ColdFusion server URL path:port number>/<Service Mapping name>/api-docs/<resourcePath name>
You can access resource listing by using the same path as above without the resourcePath name. (<ColdFusion server URL path:port number>/Service Mapping name>/api-docs)
Service Mapping name is the name that you specify while registering your REST application in ColdFusion server.
For example, localhost:8500/test/api-docs/studentService
The swagger API document generated from the sample studentservice.cfc REST CFC file appears as shown in the following api document:
{
"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 and Swagger mapping structure
You can compare CFC field types and Swagger field types from the following mapping structures.
Resource listing schema
The Resource Listing serves as the root document for the API description. It contains general information about the API and an inventory of the available resources.
Swagger doc Field Name |
Type |
Description |
CF Fields |
SwaggerVersion |
String |
Required. Specifies the Swagger Specification version being used. |
Update programmatically using API Manager |
apis |
Resource Object |
Required. Lists the resources to be described by this specification implementation. The array can have 0 or more elements |
N/A |
apiVersion |
string |
Provides the version of the application API |
Modify using application.cfc file |
info |
Info Object |
Provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience. |
Modify using application.cfc file |
authorizations |
Authorizations Object |
Provides information about the authorization schemes allowed on this API. The type of the authorization scheme. Values MUST be either"basicAuth", "apiKey" or "oauth2". |
Update programmatically using API Manager
|
API declaration schema
The API declaration provides information about an API exposed on a resource. You should have only one file described per resource. The file MUST be served in the URL described by the path field.
Swagger doc Field Name |
Type |
Description |
CF Field |
basePath |
string |
Required. The root URL serving the API. |
Add programmatically while parsing CFC |
consumes |
[string] |
A list of MIME types the APIs on this resource can consume. This is global to all APIs but can be overridden on specific API calls. |
Cfcomponent.consumes |
produces |
[string] |
A list of MIME types the APIs on this resource can produce. This is global to all APIs but can be overridden on specific API calls. |
Cfcomponent.produces |
resourcePath |
string |
The relative path to the resource, from the basePath, which this API Specification describes. |
Cfcomponent.restpath |
apis |
[API Object] |
Required. A list of the APIs exposed on this resource. There MUST NOT be more than one API Object per path in the array. |
Details in API Object |
apiVersion |
string |
Provides the version of the application API (not to be confused by the (specification version). |
N/A |
swaggerVersion |
string |
Required. Specifies the Swagger Specification version being used. |
N/A |
authorizations |
Authorizations Object |
A list of authorizations schemes required for the operations listed in this API declaration. Individual operations may override this setting. If there are multiple authorization schemes described here, it means they're all applied. |
Add programmatically as API Manager will update Authorization info |
models |
Models Object |
A list of the models available to this resource. Note that these need to be exposed separately for each API Declaration. |
Generate programmatically |
API object schema
The API Object describes one or more operations on a single path. In the apis array, there MUST be only one API Object per path.
Swagger doc Field Name |
Type |
Description |
CF Field |
description |
String |
A short description of the resource. |
Cffunction.description |
operations |
[Operation Object] |
Required. A list of the API operations available on this path. The array may include 0 or more operations. |
Details in Operation Object |
Path |
String |
Required. The relative path to the operation, from the basePath, which this operation describes. The value SHOULD be in a relative (URL) path format. |
Component.restpath + Cffunction.restpath |
Operation object schema
The Operation Object describes a single operation on a path. In the operations array, there must be only one Operation Object per method. This object includes the Data Type Fields in order to describe the return value of the operation. The type field must be used to link to other models.
This is the only object where the type may have the value of void to indicate that the operation returns no value.
Swagger doc Field Name |
Type |
Description |
CF Field |
authorization |
Authorizations Object |
A list of authorizations required to execute this operation |
Programmatically from API Manager |
consumes |
[string] |
A list of MIME types this operation can consume. |
Cffunction.consumes |
method |
String |
Required. The HTTP method required to invoke this operation. The value MUST be one of the following values: "GET", "HEAD", "POST", "PUT","PATCH", "DELETE", |
Cffunction. httpmethod |
nickname |
String |
Required. A unique id for the operation that can be used by tools reading the output for further and easier manipulation |
Cffunction.name |
notes |
String |
A verbose explanation of the operation behavior. |
Cffunction.hint |
parameters |
[Parameter Object] |
Required. The inputs to the operation. If no parameters are needed, an empty array MUST be included. |
Details in parameter object |
produces |
[string] |
A list of MIME types this operation can produce. |
Cffunction.produces |
responseMessages |
[Response Message Object] |
Lists the possible response statuses that can return from the operation. |
New parameter introduced in Cfunction |
summary |
String |
A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters. |
Cffunction.description
|
Parameter object schema
The Parameter Object describes a single parameter to be sent in an operation and maps to the parameters field in the Operation Object. This object includes the Data Type Fields in order to describe the type of this parameter. The type field must be used to link to other models.
If type is File, the consumes field must "multipart/form-data", and the paramType must be "form".
Swagger doc Field Name |
Type |
Description |
CF Field |
allowMultiple |
boolean |
Another way to allow multiple values for a "query", "header" or "path" parameter. |
Not available in ColdFusion. |
description |
string |
Recommended. A brief description of this parameter. |
Cfargument.hint |
name |
string |
Required. The unique name for the parameter. |
Cfargument.name |
paramType |
string |
Required. The type of the parameter. The value MUST be one of these values: "path", "query", "body","header", "form" Note: As per spec swagger dosen’t support "Cookie", "Matrix" paramtype which we have in ColdFusion |
Cfargument. restargsource |
required |
boolean |
A flag to note whether this parameter is mandatory. |
Cfargument.required |
CFC/Swagger/Java types comparison
CFC |
Swagger |
Java |
Additional information |
string |
string |
string |
|
uuid |
string |
string |
|
guid |
string |
string |
|
query |
custom model |
coldfusion.xml.rpc.DocumentQueryBean |
|
void |
void |
|
for argument map to "body" |
numeric |
number(format double) |
Double |
|
boolean |
boolean |
boolean |
|
date |
string(format date) |
java.util.Calendar |
|
any |
object |
java.lang.Object |
|
array |
array of objects |
java.lang.Object[] |
|
binary |
?? |
byte[] |
|
struct |
custom model |
java.util.Map |
|
xml |
string |
org.w3c.dom.Documents |
|