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

cbSwagger

v2.7.0+169 Modules

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.

Resources

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
	// Routes to exclude by prefix.  Routes beginning with this prefix will be excluded
	"excludeRoutesPrefix" : [ "cbswagger", "relax" ],
	// Any routes to exclude
	"excludeRoutes"	: [],
	"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",

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

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

	// 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 default declaration of Security Requirement Objects to be used across the API.
	// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securityRequirementObject
	// Only one of these requirements needs to be satisfied to authorize a request.
	// Individual operations may set their own requirements with `@security`
	"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 (metadata), which will be picked up and included in your documentation.

The content body of these function metadata/attributes may be provided as:

  • JSON
  • plain text
  • $ref file pointer

Here are some additional pointers for you:

  • Metadata attributes using a response- prefix in the annotation will be parsed as responses. For example @response-200 { "description" : "User successfully updated", "schema" : "/resources/apidocs/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 parameters 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.
  • Security Requirement Objects defined in the cbSwagger config will be displayed on every API method, except methods that override the default with @security. You may use the name of a security scheme, a JSON array of Security Requirement Objects, or a file pointer. Security Requirement Objects must have the same name as a Security Scheme Object defined under components in cbSwagger settings.
  • 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 treated 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
  • tags : A list of tags to include in the operation metadata: @tags Authentication,Authors.

Basic Example:

/**
 * Add a new user into the system
 *
 * @tags Users,Authentication
 */
function add( event, rc, prc )
	parameters="~users.add.parameters.json"
	responses="~users.add.responses.json"
	security="APIKey"
	x-SomeAdditionalInfo="Here is some additional information on this path"
{

	...[ Your code here ]...

}

Example using file pointers:

/**
* @hint Adds a new user
* @x-parameters ~users.add.parameters.json##user
* @responses ~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 )

Note: Because CFML has its own parameters key within the function metadata, we would pull in a document of parameters using x-parameters, which will appear as parameters in the swagger method definition

/**
 * @hint Adds a new user
 * @x-parameters ~users.add.parameters.json
 * @responses ~users.add.responses.json
 * @x-SomeAdditionalInfo Here is some additional information on this path
 * @security ~users.add.security.json
 * @requestBody {
 * 	"description" : "User to add",
 * 	"required" : true,
 * 	"content" : {
 * 		"application/json" : {
 * 			"schema" : { "$ref" : "/includes/apidocs/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" }
 * @security [ { "APIKey": [] } ]
 * @response-default { "description" : "User successfully updated", "content" : { "application/json" : { "schema" : { "$ref" : "/resources/apidocs/schema.json##user" } } } }
 */
function update( event, rc, prc ) description="Updates a user"{
}

~ expand path

The shortcut notation to expand the path to the samplesPath setting is by using the ~ prefix. However, please note that this prefix only works on the annotations within a component NOT within a json document.

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

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


[2.7.0] => 2021-OCT-1

Added

  • Added the ability to excludes routes by prefix

[2.5.1] => 2021-MAY-12

Fixed

  • Regression on @tags being json syntax

[2.5.0] => 2021-MAY-10

Added

  • Added the ability to add @tags to annotations so they can show up on the operations metadata as array of tags

[2.4.0] => 2021-MAY-04

Removed

  • Removed externalDocs from the info struct as it is not supported on the OpenApi Spec v3.

Changed

  • operationID renamed to x-coldbox-operation since they are ColdBox centric. It was also causing issues using operationID as it needed to be unique across the entire swagger document.

[2.3.0] => 2020-SEP-08

Added

  • Add CORS support for cbswagger endpoint #25

[2.2.1] => 2020-MAY-12

Fixed

  • On lucee the displayName defaults to Component, skipping this default to select the correct operationId for the resource
  • The moduleName hint for the appendFunctionInfo was mispelled

[2.2.0] => 2020-MAY-12

Added

  • When defining external files in annotations, you can now prefix them with ~ and this will expand to the module setting of samplesPath. This way you can write your annotations in a more cleaner manner.
  • Auto-publishing of changelog's to github
  • New changelog looks according to keepachangelog.com

[2.1.1] => 2020-MAY-06

  • Updates to support ColdBox 6

[2.1.0] => 2020-APR-16

Features

  • Allow @security annotation to override the security mechanisms defined in config. The value can be a JSON array of security directives, a file pointer, or for convenience the name of a security schema. See readme for examples.
  • Support for discovering responses and examples by conventions in the resources/apidocs folder convention. See readme for examples.
  • Ability to exclude routes from the generated spec via the excludeRoutes configuration key.

Improvements

  • Add default samplesPath config item to resources/apidocs in the ModuleConfig
  • Add convention samples parsing and refactor segment parsing to separate methods

Bugs

  • Fixes for new router syntax not parsing actions correctly or not taking into account actions attached to verbs

[2.0.0] => 2019-SEP-02

  • 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

$ box install cbSwagger

No collaborators yet.
     
  • {{ getFullDate("2016-10-01T08:56:12Z") }}
  • {{ getFullDate("2022-11-07T21:22:08Z") }}
  • 15,304
  • 191,917