User Guide Cancel

Generate Swagger documents

  1. ColdFusion Tools User Guide
  2. Performance Monitoring Toolset
    1. Overview of ColdFusion Performance Monitoring Toolset
    2. Auto-discovery of ColdFusion nodes and clusters
    3. Code profiler in ColdFusion Performance Monitoring Toolset
    4. Configure ColdFusion Performance Monitoring Toolset settings
    5. Install ColdFusion Performance Monitoring Toolset
    6. View cloud metrics
    7. Monitor GraphQL in Performance Monitoring Toolset
    8. Configure TLS/SSL and Authentication for Elasticsearch 8.x  in Performance Monitoring Toolset
    9. View cluster and node metrics
    10. View data source metrics
    11. View external services
    12. View incoming services
    13. View list of sites and busy connections
    14. View topology of sites
    15. Datastore Health Monitoring
    16. Performance Monitoring Toolset Update 1
    17. Secure Performance Monitoring Toolset with HTTPS/SSL
    18. Performance Monitoring Toolset deployment guide
  3. Use ColdFusion Builder
    1. About ColdFusion Builder
    2. System requirements | ColdFusion Builder
    3. Install ColdFusion Builder
    4. Edit code in ColdFusion Builder
    5. Manage servers in ColdFusion Builder
    6. Manage projects in ColdFusion Builder
    7. What's new in Adobe ColdFusion Builder (2018 release)
    8. Frequently Asked Questions (FAQ) | Adobe ColdFusion Builder (2018 release)
    9. Debug applications in ColdFusion Builder
    10. ColdFusion Builder workbench
    11. ColdFusion Builder extensions
    12. Debugging Perspective in ColdFusion Builder
    13. Build mobile applications using ColdFusion Builder
    14. Bundled ColdFusion Server
    15. Debug mobile applications in ColdFusion Builder
    16. Use extensions in ColdFusion Builder
  4. Coldfusion API Manager
    1. Overview of Adobe ColdFusion API Manager
    2. Features in ColdFusion API Manager
    3. Get started with ColdFusion API Manager
    4. Install ColdFusion API Manager
    5. Authentication types
    6. Create and publish APIs
    7. Administrator
    8. Subscriber
    9. Throttling and rate limiting
    10. Notifications
    11. Connectors
    12. Set up cluster support
    13. Integrate ColdFusion and API Manager
    14. Metrics and Logging in API Manager
    15. Generate Swagger documents
    16. Configure SSL
    17. Known issues in this release
    18. Policies in ColdFusion API Manager
    19. Create a Redis cluster
    20. Multitenancy in API Manager
    21. Docker images for ColdFusion API Manager

Overview

Swagger is a project specification that is used to describe and document RESTful APIs. In Adobe ColdFusion (2016 release), 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, refer to 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. 

Create your 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. 

// student.cfc
component
{
 property string name;
 property numeric age;
}
// address.cfc
component
{
 property string buildingName;
 property numeric flatNumber;
 property string locality;
  property string province;
}

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 response messages attribute

A new attribute named responseMessages has been introduced in Adobe 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. 

Register your CFC application

Start ColdFusion Administrator. Click Data & Services > REST Services on the left pane and add configuration values as per the instructions in the following dialog.

  1. Enter the root path where REST CFCs are available in your system. Alternatively you can click Browse Server and choose the path where the CFC application resides. 
  2. Enter the host name for the REST service. For example, localhost:8500 
  3. Enter the Service Mapping string name. For example, http://localhost/rest/{service mapping}/test 
  4. Select the check box if you want to set the application as default while calling the web service.

Access swagger api-docs 

The Swagger representation of the API comprises two file types:

The Resource Listing - This root document contains general API information and lists the resources. Each resource has its own URL that defines the API operations on it.

{
    "apiVersion":"2.0",
    "swaggerVersion":"1.2",
    "apis":[
        {
            "path":"/studentService"
        }
    ],
    "info":{
        "title":"this is title",
        "description":"this is description",
        "termsOfServiceUrl":"url is here",
        "contact":"xyz@adobe.com",
        "license":"adobe 1.0",
        "licenseUrl":"http://abc.com"
    }
}

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"
                }
            }
        }
    }
}

Import API from CF REST services

As a Publisher, during API creation you can import CF REST API services. Before choosing this option, ensure that you add the CF server in API Manager. 

Note:

Add the CF server only when you are accessing API Manager remotely.

API Manager can be installed over ColdFusion in your system. API Manager is installed in cfusion /ApiManager path. For more information, refer to ColdFusion and API Manager integration feature. 

Add CF server in API Manager

Start API Manager in Administrator mode. Click CF Discovery Server Configuration on the left pane. Add the configuration values as shown in the sample snapshot below. 

Import API

Start API Manager portal. Click Create New API and click Import REST API from ColdFusion.

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 of the specification. 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 clients can use this metadata, 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. Specify only one file per resource. Save the file 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. The MIME types are 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. The MIME types are 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 override this setting. If there are multiple authorization schemes described here, it means they're all applied.

Add programmatically as API Manager updates Authorization info

models

Models Object

A list of the models available to this resource. Expose the models 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 includes zero 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 to describe the return value of the operation. The type field must be used to link to other models.

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 call the operation.The value MUST be one of the following values:

 "GET", "HEAD", "POST", "PUT","PATCH", "DELETE", 
"OPTIONS". The values MUST be in uppercase.

Cffunction. httpmethod

nickname

String

Required. A unique id for the operation that is 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 fewer 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 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 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 array of byte byte[]  
struct custom model java.util.Map  
xml string org.w3c.dom.Documents  

 Adobe

Get help faster and easier

New user?