FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

cbSwagger

v2.0.0+94 Public

Build Status

Welcome to the ColdBox Swagger Module

This module automatically generates OpenAPI ( fka Swagger ) documenation from your configured application and module routes. This module utilizes the v3.0.2 OpenAPI Specification

License

Apache License, Version 2.0.

Important links

  • https://github.com/coldbox-modules/cbSwagger

Resources

  • https://swagger.io/specification
  • https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
  • https://idratherbewriting.com/learnapidoc/pubapis_openapi_tutorial_overview
  • https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

System Requirements

  • Lucee 5+
  • Adobe ColdFusion 2016+

Pre-requisites

To operate, the module requires that SES routing be enabled in your application. For more information read the official documentation.

Install cbSWagger ( via Commandbox )

box install cbSwagger

Note: Omit the box from your command, if you are already in the Commandbox interactive shell

Configure cbSwagger to auto-detect your API Routes

By default, cbSwagger looks for routes beginning with /api/* prefix. By adding a cbSwagger configuration key to your Coldbox configuration, you can add additional metadata to the OpenAPI JSON produced by the module entry point and configure this module for operation.

  • routes:array : An array of route prefixes to search for and add to the resulting documentation.
  • defaultFormat:string : The default output format of the documentation. Valid options are json and yml.

A full configuration example is provided below:

cbswagger = {
	// The route prefix to search.  Routes beginning with this prefix will be determined to be api routes
	"routes" : [ "api" ],
	// The default output format: json or yml
	"defaultFormat" : "json",
	// A convention route, relative to your app root, where request/response samples are stored ( e.g. resources/apidocs/responses/[module].[handler].[action].[HTTP Status Code].json )
	"samplesPath" : "resources/apidocs",
	// Information about your API
	"info"		:{
		// A title for your API
		"title" 			: "My Awesome API",
		// A description of your API
		"description" 		: "This API produces amazing results and data.",
		// A terms of service URL for your API
		"termsOfService"	: "",
		//The contact email address
		"contact" 		:{
			"name": "API Support",
			"url": "http://www.swagger.io/support",
			"email": "[email protected]"
		},
		//A url to the License of your API
		"license": {
			"name": "Apache 2.0",
			"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
		},
		//The version of your API
		"version":"1.0.0"
	},

	// Tags
	"tags" : [
		{
			"name": "pet",
			"description": "Pets operations"
		}
	],

	// https://swagger.io/specification/#externalDocumentationObject
	"externalDocs" : {
		"description": "Find more info here",
		"url": "https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/"
	},

	// https://swagger.io/specification/#serverObject
	"servers" : [
		{
			"url" 			: "https://mysite.com/v1",
			"description" 	: "The main production server"
		},
		{
			"url" 			: "http://127.0.0.1:60299",
			"description" 	: "The dev server"
		}
	],

	// An element to hold various schemas for the specification.
	// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject
	"components" : {

		// Define your security schemes here
		// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject
		"securitySchemes" : {
			"UserSecurity" : {
				// REQUIRED. The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".
				"type" 			: "http",
				// A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
				"description" 	: "HTTP Basic auth",
				// REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
				"scheme" 		: "basic"
			},
			"APIKey" : {
				"type" 			: "apiKey",
				"description" 	: "An API key for security",
				"name" 			: "x-api-key",
				"in" 			: "header"
			}
		}
	},

	// A declaration of which security mechanisms can be used across the API.
	// The list of values includes alternative security requirement objects that can be used.
	// Only one of the security requirement objects need to be satisfied to authorize a request.
	// Individual operations can override this definition.
	"security" : [
		{ "APIKey" : [] },
		{ "UserSecurity" : [] }
	]
};

Outputting Documentation (json|yml)

You can visit the API documentation by hitting the /cbSwagger route. This will trigger the default format (json) to be sent to the output.

Format Parameter

You can force the format by using the ?format={format} in the URI. The valid options are json and yml

http://localhost/cbSwagger?format=yml
http://localhost/cbSwagger?format=json
http://localhost/cbSwagger/json
http://localhost/cbSwagger/yml

Handler Introspection & Documentation attributes

cbSwagger will automatically introspect your API handlers provided by your routing configuration. You may provide additional function attributes, which will be picked up and included in your documentation. The content body of these attributes may be provided as JSON, plain text, or may provided a file pointer which will be included as a $ref attribute. Some notes on function attributes:

  • Metadata attributes using a response- prefix in the annotation will be parsed as responses. For example @response-200 { "description" : "User successfully updated", "schema" : "/includes/resources/schema.json##user" } would populate the 200 responses node for the given method ( in this case, PUT /api/v1/users/:id ). If the annotation text is not valid JSON or a file pointer, this will be provided as the response description.
  • Metadata attributes prefixed with param- will be included as paramters to the method/action. Example: @param-firstname { "type": "string", "required" : "false", "in" : "query" } If the annotation text is not valid JSON or a file pointer, this will be provided as the parameter description and the parameter requirement will be set to false.
  • Parameters provided via the route ( e.g. the id in /api/v1/users/:id ) will always be included in the array of parameters as required for the method. Annotations on those parameters may be used to provide additional documentation.
  • You may also provide paths to JSON files which describe complex objects which may not be expressed within the attributes themselves. This is ideal to provide an endpoint for parameters and responses If the atttribute ends with .json, this will be included in the generated OpenAPI document as a $ref include.
  • Attributes which are not part of the swagger path specification should be prefixed with an x-, x-attributes are an official part of the OpenAPI Specification and may be used to provide additional information for your developers and consumers
  • hint attributes, provided as either comment @ annotations or as function body attributes will be treaded as the description for the method
  • description due to variances in parsing comment annotations, description annotations must be provided as attributes of the function body. For example, you would use function update( event, rc, prc ) description="Updates a user"{} rather than @description Updates a user

Basic Example:

//(POST) /api/v1/users
function add( event, rc, prc )
	description="Adds a new user"
	parameters="/includes/resources/users.add.parameters.json"
	responses="/includes/resources/users.add.responses.json"
	x-SomeAdditionalInfo="Here is some additional information on this path"
{

	...[ Your code here ]...

}

Example using file pointers:

/**
* @hint Adds a new user
* @x-parameters /includes/resources/users.add.parameters.json##user
* @responses /includes/resources/users.add.responses.json
* @x-SomeAdditionalInfo Here is some additional information on this path
*/
function add( event, rc, prc ){

	...[ Your code here ]...

}

Example using JSON ( + file pointers )

/**
 * @hint Adds a new user
 * @parameters /includes/resources/users.add.parameters.json##user
 * @responses /includes/resources/users.add.responses.json
 * @x-SomeAdditionalInfo Here is some additional information on this path
 * @requestBody {
 * 	"description" : "User to add",
 * 	"required" : true,
 * 	"content" : {
 * 		"application/json" : {
 * 			"schema" : { "$ref" : "/includes/resources/NewUser.json" }
 * 		}
 * 	}
 * }
 */
function add( event, rc, prc ){
}


/**
 * @param-firstname { "schema" : { "type": "string" }, "required" : "false", "in" : "query" }
 * @param-lastname { "schema" : { "type": "string" }, "required" : "false", "in" : "query" }
 * @param-email { "schema" : { "type": "string" }, "required" : "false", "in" : "query" }
 * @response-default { "description" : "User successfully updated", "content" : { "application/json" : { "schema" : { "$ref" : "/includes/resources/schema.json##user" } } } }
 */
function update( event, rc, prc ) description="Updates a user"{
}

Using convention paths to generate documentation schema and samples

Conventions also exist, which will allow you to place JSON files within a conventions directory, defined by the samplesPath setting, which will automatically be included as part of your documentation. The default samples path is resources/apidocs. A JSON file placed, for example, at the location of resources/apidocs/responses/api.v1.Users.add.201.json, would automatically be picked as the 201 status code response for the add method of the Users handler, within the api.v1 directory.

In addition to the responses sub-directory, the directories of parameters and responseBody will also be inspected for content which matches the route/event being parsed. The latter two directories are parsed as-is, and are assumed to be in a valid Swagger specification format.

File naming conventions supported include:

  • [handler].[methodName].json - all sample types
  • [moduleName].[handler].[methodName].json - all sample types
  • [handler].[methodName](.[status code]).json - responses with or without status codes
  • [moduleName].[handler].[methodName](.[status code]).json - responses with or without status codes

Operation Ids

You can influence the operation Ids by adding a displayName to your handler CFC.

component displayName="API.v1.Users"{

}

Copyright Since 2016 Ortus Solutions, Corp www.ortussolutions.com


HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

CHANGELOG

2.0.0

  • feature: Upgraded to swagger-sdk 2.0.0 to support OpenAPI 3.0.x. A great guide on migrating is here: https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

  • Migrated cbSwagger settings to the moduleSettings struct instead of top-level in the config/ColdBox.cfc. Make sure you move your settings.

  • feature : You can now pass a format to the /cbSwagger endpoint to either get the OpenAPI doc as json or yml. Eg: /cbswagger?format=yml

  • feature : You have two distinct routes for the json and yml formats: /cbSwagger/json and /cbSwagger/yml

  • You can choose your default output format via the module settings: defaultFormat setting. Valid options are json and yml

  • features : Support for ColdBox 5 event routing and response routing.

  • improvement : You can now tag your handlers with a displayName that will be used for operation ID building

  • improvement : Improved the way operation Ids are reported so they can be unique when reusing handler actions.

  • improvement : Refactored createLinkedHashMap() -> structNew( "ordered" )

  • improvement: Removed lucee 4.5, acf11 support.

1.4.1

  • Fix for detecting ColdBox 5

1.4.0

  • Update build process for new module standards
  • ColdBox 5 Compatiblity for inherited entry points
  • Non RESTFul action params where not being translated on routes.
  • Fixed int32 to integer on examples and tests so they can validate in the schema

1.3.0

  • Added Editor standards
  • Fix to modules invocation path on RouteParser when no cfmapping defined.
  • Updates to readme
  • Set the contact object and license object according to spec 2 defaults
  • Default the API schemes to http/s
  • Dropped cf10 from automated tests
  • Added API Docs to S3 via Travis

1.2.1

  • Fixes a bug where an error was thrown when an api route does not contain a handler
  • Implements parsing of Coldbox route parameter types

1.2.0

  • Adds new function metadata handling for parameters and responses
  • Auto maps hints provided in function metadata to as method descriptions

1.1.2

  • Add $ref sanitization and inherited metadata introspection
  • Add the ability to handle arrays returned from $ref keys. Prepends moudule routing to operation id
  • ACF syntax corrections and add better throw for attempts to parse component with syntax errors

1.1.0

  • Normalization to new module templates
  • HTTP Verbs should be lower case #1

1.0.3

  • Exception when handler or module does not exist in a route.

1.0.2

  • Overall syntax Ortus standards
  • Some var scoping issues
  • Added persistence and injections to services
  • Added more documentation to handler, services and readme
  • Added swagger-sdk as a module dependency

1.0.1

  • Add module introspection
  • Forgebox integration updates

1.0.0

  • Initial Module Release

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
Current
2.1.0-snapshot Sep 02 2019 05:59 PM Sep 02 2019 05:59 PM
Version History
2.0.0+94 Sep 02 2019 05:59 PM Sep 02 2019 05:59 PM
2.0.0-snapshot Sep 02 2019 05:34 PM Sep 02 2019 05:34 PM
1.5.0-snapshot Oct 04 2018 05:54 PM Oct 04 2018 05:54 PM
1.4.1+70 Oct 05 2018 04:01 PM Oct 05 2018 04:01 PM
1.4.0+68 Oct 04 2018 05:50 PM Oct 04 2018 05:50 PM
1.4.0-snapshot Jan 26 2018 12:40 PM Oct 04 2018 05:46 PM
1.3.0+62 Jan 26 2018 12:40 PM Jan 26 2018 12:40 PM
1.3.0-snapshot Jan 26 2018 12:03 PM Jan 26 2018 12:03 PM
1.2.1+58 Nov 02 2017 08:21 PM Nov 02 2017 08:21 PM
1.2.1-snapshot Nov 02 2017 08:09 PM Nov 02 2017 08:09 PM
1.2.0+55 Oct 30 2017 11:07 AM Oct 30 2017 11:07 AM
1.2.0-snapshot Oct 18 2017 06:29 AM Oct 04 2018 05:40 PM
1.1.2+48 Sep 09 2017 04:49 PM Sep 09 2017 04:49 PM
1.1.2-snapshot Sep 09 2017 04:26 PM Sep 09 2017 04:26 PM
1.1.1-snapshot Sep 09 2017 10:56 AM Sep 09 2017 10:56 AM
1.1.0+40 Jul 03 2017 02:43 PM Jul 03 2017 02:43 PM
1.1.0-snapshot Jul 03 2017 12:20 PM Jul 03 2017 12:20 PM
1.0.3+29 Oct 13 2016 02:42 PM Oct 13 2016 02:42 PM
1.0.2+24 Oct 03 2016 09:38 PM Oct 03 2016 09:38 PM
1.0.1+22 Oct 02 2016 02:29 PM Oct 02 2016 02:29 PM
1.0.1+21 Oct 02 2016 12:31 PM Oct 02 2016 12:31 PM
1.0.1+00002 Oct 01 2016 05:29 PM Oct 01 2016 05:29 PM
1.0.0+00002 Oct 01 2016 08:58 AM Oct 01 2016 08:58 AM

 

$ box install cbSwagger

No collaborators yet.
     
  • Oct 01 2016 08:56 AM
  • Sep 02 2019 05:59 PM
  • 2,888
  • 5,609
  • 20,977