FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...
This module automatically generates OpenAPI ( fka Swagger ) documenation from your configured application and module routes. This module utilizes the v3.0.2 OpenAPI Specification
Apache License, Version 2.0.
To operate, the module requires that SES routing be enabled in your application. For more information read the official documentation.
box install cbSwagger
Note: Omit the
box
from your command, if you are already in the Commandbox interactive shell
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" : [] }
]
};
You can visit the API documentation by hitting the /cbSwagger
route. This will trigger the default format (json) to be sent to the output.
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
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:
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.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
.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..json
, this will be included in the generated OpenAPI document as a $ref include.x-
, x-attributes are an official part of the OpenAPI Specification and may be used to provide additional information for your developers and consumershint
attributes, provided as either comment @
annotations or as function body attributes will be treaded as the description for the methoddescription
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 codesYou 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
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
"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12
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.
int32
to integer
on examples and tests so they can validate in the schema$ref
sanitization and inherited metadata introspection$ref
keys. Prepends moudule routing to operation idhandler
or module
does not exist in a route.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.
$
box install cbSwagger