API Documentation

Generate OpenAPI documentation for your ColdBox APIs automatically with cbswagger.

cbswagger generates OpenAPI (v3) documentation directly from your ColdBox routes and handler metadata — your API docs stay in sync with your code because they come from it.

box install cbswagger

📖 Full documentation: ForgeBox · GitHub

Quick Example

Install it, and your route table becomes an OpenAPI document:

// config/Router.bx — routes you already have
route( "/api/users" ).toHandler( "users.index" )
route( "/api/users/:id" ).toHandler( "users.show" )

Then enrich handlers with metadata cbswagger reads:

BoxLang

/**
 * @route GET /api/users
 * @summary List all users
 * @tags Users
 * @response 200 {array} List of users
 */
function index( event, rc, prc ){
    event.renderData( type : "json", data : userService.list() )
}

CFML

/**
 * @route GET /api/users
 * @summary List all users
 * @tags Users
 * @response 200 {array} List of users
 */
function index( event, rc, prc ){
    event.renderData( type : "json", data : userService.list() )
}

The generated spec is served from your app (by default at /cbswagger) and feeds Swagger UI, Postman, or any OpenAPI tooling.

When to Use It

• Public APIs that need always-current documentation

• Teams generating client SDKs from an OpenAPI spec

• Contract testing against a live spec

See Also

• Resourceful Routes — the route shapes cbswagger documents best

• REST Handler — building the APIs it documents