Download OpenAPI (Swagger) Spec Template For ColdFusion APIs

Contents show

Introduction

If you build REST endpoints with ColdFusion (Adobe ColdFusion or Lucee), you still need clear, accurate API documentation that teammates, integrators, and QA can trust. This downloadable OpenAPI (Swagger) specification template gives you a ready-to-use, Standards-compliant starting point to describe your CFML APIs in YAML or JSON, preview them in Swagger UI, validate them with linters, and share interactive docs. It removes guesswork, establishes a repeatable structure, and speeds up Onboarding for your team and consumers.

This article explains exactly what’s included, how to set it up, and Best practices for adapting the spec to your ColdFusion project. Wherever you see your stack mentioned—ColdBox, FW/1, Taffy, or raw CFScript—this template will fit right in.

What You’ll Get

Download or copy the following ready-made assets. They are OpenAPI 3.0.3-compliant, designed for CFML-backed REST APIs, and easy to integrate:

openapi.yaml (primary) and openapi.json (compiled) spec files
Swagger UI bundle and a minimal index.html pre-wired to your spec
A CFML snippet to serve /openapi.json dynamically (optional)
Postman and Insomnia collections generated from the spec
Spectral linter config for CI/CD validation
Example Security schemes (API Key, Bearer JWT, OAuth2)
Reusable components: error model, pagination, common headers, and example payloads
README with setup, validation, and Deployment tips

Quick contents overview:

File/Folder	Description	Purpose
openapi.yaml	Main OpenAPI 3.0.3 spec	Editable source of truth
openapi.json	JSON output of the spec	For tools that prefer JSON
/swagger-ui/	Swagger UI dist + index.html	Self-hosted interactive docs
/collections/	Postman and Insomnia exports	Testing and collaboration
/cfml/serve-openapi.cfm	CFML example to serve spec	Dynamic route for /openapi.json
.spectral.yaml	Linting rules	Quality checks in CI/CD
README.md	Quick instructions	Onboarding and usage

Tip: Prefer YAML for authoring and convert to JSON for tools that need it.

Overview

OpenAPI (formerly Swagger) is the industry standard for API contracts. The template below is tailored for ColdFusion environments (Adobe ColdFusion and Lucee) and includes best-practice structures for paths, components, tags, examples, Security, and Error handling.

Key Features:

Works with Swagger UI, ReDoc, and API Gateways (Kong, Apigee, Azure API management)
Integrates into ColdFusion sites as static files or as a dynamic endpoint
Validates with Spectral to catch issues before Deployment
Supports response examples, parameter definitions, and reusable schemas

Benefits

Faster onboarding: new developers see endpoints, parameters, and examples immediately.
Consistent documentation: reuse schemas and headers across multiple APIs.
Better testing: import to Postman/Insomnia for quick smoke tests.
Automation-friendly: openapi-generator and CI/CD validation reduce manual effort.
Consumer confidence: interactive docs let teams try your REST API with live servers.

What’s Inside the Template (Detailed)

The template is intentionally opinionated for CFML services:

Servers block for dev, staging, and production
Tags for logical grouping (Auth, Users, Orders, Admin)
Common error response (Problem+JSON-style) with consistent fields
Pagination and filtering parameters ready to reuse
Security schemes for:
- API Key (header-based X-API-Key)
- Bearer token (JWT)
- OAuth2 authorization code flow
Global components for headers (RateLimit, Request-Id), standard enums, and date/time formats

How to Download and Use

You can either:

Download the ZIP archive (if a link was provided by your team), or
Copy the code blocks below into files in your project (recommended if you need immediate use)

Once the files are in place, follow the steps in “Step-by-Step Setup” to wire up Swagger UI and serve your OpenAPI spec from your ColdFusion application.

Sample OpenAPI 3.0.3 Template (YAML)

Save this as openapi.yaml at the root of your docs folder (for example, /api-docs/openapi.yaml). Adjust names, URLs, and schemas to match your API.

openapi: 3.0.3
info:
title: Example ColdFusion API
description: >
Standardized OpenAPI (Swagger) specification template for CFML-based services.
Replace sample endpoints with your own paths and components.
version: 1.0.0
contact:
name: API Team
email: api-team@example.com
servers:

url: https://api-dev.example.com
description: Development
url: https://api-staging.example.com
description: Staging
url: https://api.example.com
description: Production
tags:
name: Auth
description: Authentication and authorization
name: Users
description: User management
paths:
/auth/login:
post:
tags: [Auth]
summary: Authenticate user with email and password
requestBody:
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/LoginRequest’
examples:
default:
value:
email: jane@example.com
password: secret123
responses:
‘200’:
description: Login successful
headers:
X-RateLimit-Remaining:
$ref: ‘#/components/headers/RateLimitRemaining’
content:
application/json:
schema:
$ref: ‘#/components/schemas/AuthResponse’
‘401’:
$ref: ‘#/components/responses/Unauthorized’
/users:
get:
tags: [Users]
summary: List users with paging
parameters:
- $ref: ‘#/components/parameters/Page’
- $ref: ‘#/components/parameters/PageSize’
  security:
- BearerAuth: []
  responses:
  ‘200’:
  description: Paged list of users
  headers:
  X-Total-Count:
  description: Total number of items available.
  schema:
  type: integer
  content:
  application/json:
  schema:
  $ref: ‘#/components/schemas/UserList’
  ‘401’:
  $ref: ‘#/components/responses/Unauthorized’
  ‘500’:
  $ref: ‘#/components/responses/ServerError’
  components:
  securitySchemes:
  ApiKeyAuth:
  type: apiKey
  in: header
  name: X-API-Key
  BearerAuth:
  type: http
  scheme: bearer
  bearerFormat: JWT
  OAuth2Auth:
  type: oauth2
  flows:
  authorizationCode:
  authorizationUrl: https://auth.example.com/oauth/authorize
  tokenUrl: https://auth.example.com/oauth/token
  scopes:
  users.read: Read user data
  users.write: Modify user data
  parameters:
  Page:
  name: page
  in: query
  description: Page index (1-based)
  schema:
  type: integer
  minimum: 1
  default: 1
  PageSize:
  name: pageSize
  in: query
  description: Number of items per page
  schema:
  type: integer
  minimum: 1
  maximum: 100
  default: 20
  headers:
  RateLimitRemaining:
  description: Remaining requests in the current window
  schema:
  type: integer
  responses:
  Unauthorized:
  description: Unauthorized
  content:
  application/json:
  schema:
  $ref: ‘#/components/schemas/Error’
  ServerError:
  description: Server error
  content:
  application/json:
  schema:
  $ref: ‘#/components/schemas/Error’
  schemas:
  LoginRequest:
  type: object
  required: [email, password]
  properties:
  email:
  type: string
  format: email
  password:
  type: string
  format: password
  AuthResponse:
  type: object
  properties:
  access_token:
  type: string
  description: JWT access token
  token_type:
  type: string
  example: Bearer
  expires_in:
  type: integer
  example: 3600
  User:
  type: object
  properties:
  id:
  type: string
  example: U123
  email:
  type: string
  format: email
  createdAt:
  type: string
  format: date-time
  UserList:
  type: object
  properties:
  items:
  type: array
  items:
  $ref: ‘#/components/schemas/User’
  page:
  type: integer
  pageSize:
  type: integer
  Error:
  type: object
  properties:
  type:
  type: string
  example: about:blank
  title:
  type: string
  example: Unauthorized
  status:
  type: integer
  example: 401
  detail:
  type: string
  example: Invalid credentials

Step-by-Step Setup

Follow these steps to install and publish your OpenAPI docs alongside your ColdFusion application.

1) Place Files in Your Project

Create a folder in your webroot, for example: /api-docs/
Add openapi.yaml (and optionally openapi.json) to /api-docs/
Copy the /swagger-ui/ folder into /api-docs/swagger-ui/
Optional: Add /cfml/serve-openapi.cfm if you want a dynamic /openapi.json endpoint

Tip: Make sure your web server serves .yaml with a proper MIME type (text/yaml or application/yaml). On IIS/Apache/Nginx, add a mapping if needed.

2) Wire Up Swagger UI

Open /api-docs/swagger-ui/index.html and point it to your spec:

Browse to https://your-host/api-docs/swagger-ui/ to see interactive documentation.

3) Optionally Serve /openapi.json via CFML

If you want a dynamic endpoint (useful for CI or gateways), add a route like /openapi.json and serve the file. Example CFML (serve-openapi.cfm):

// Read YAML and convert to JSON if needed; or serve a static JSON file.
// Simplest approach: serve the JSON file
filePath = expandPath(“../openapi.json”); // Adjust path
cfheader(name=”Content-Type”, value=”application/json; charset=utf-8″);
writeOutput(fileRead(filePath));

Map /openapi.json to this file using your framework’s routing (ColdBox, FW/1) or a simple rewrite rule.

4) Validate the Spec

Install Spectral (Node): npm i -g @stoplight/spectral-cli
Run: spectral lint api-docs/openapi.yaml
Fix any warnings or errors to maintain quality.

You can also use:

swagger-cli: npx swagger-cli validate api-docs/openapi.yaml
Online validators (Swagger Editor, Stoplight)

5) Import for Testing

Open Postman or Insomnia and import /collections/postman.json or directly import openapi.yaml.
Verify endpoints and example requests. Share collections with QA and partners.

6) Secure Access (Optional)

If Swagger UI should not be public:

Protect /api-docs/ via web server auth (IIS/Apache) or route-level auth in your framework.
Alternatively, host Swagger UI on a separate admin domain.

7) CI/CD Integration

Add spectral lint to your pipeline to fail builds on invalid specs.
Commit openapi.yaml; treat it as a “contract” for your API.
Optionally generate SDKs: openapi-generator can create client libraries (Java, TypeScript, Python, etc.) for your consumers.

Supported Environments

Stack	Versions	Notes
Adobe ColdFusion	2018, 2021, 2023	Works with built-in Tomcat; ensure MIME types set for .yaml
Lucee	5.x and newer	Works on Tomcat/Undertow; verify resource mappings
Web Servers	IIS, Apache, Nginx	Static serving for /api-docs and /swagger-ui
Java	11, 17 (common CF setups)	Match your CF engine requirements

How to Customize for Your ColdFusion framework

ColdBox

Place /api-docs/ under webroot or a public module folder.
Add a route to /openapi.json if you prefer a dynamic endpoint.
Use handlers/interceptors to apply security middleware in production.

FW/1

Serve Swagger UI as a public sub-app or static folder.
Map a controller action to stream openapi.json with cfcontent.

Taffy

Keep your Taffy routes; the OpenAPI spec simply documents them.
If you use Taffy’s built-in docs, consider linking to Swagger UI for richer examples.

Pure CFML (No Framework)

Use URL rewrites (IIS/Apache) to map /openapi.json to /api-docs/cfml/serve-openapi.cfm.
Serve Swagger UI statically from /api-docs/swagger-ui/.

Best practices

Keep the spec versioned with your API (info.version and path versions like /v1).
Use reusable components for parameters, headers, and schemas to prevent duplication.
Provide examples for request bodies and responses; they’re invaluable for consumers.
Document Authentication thoroughly (securitySchemes + security at path/operation level).
Include error responses for typical failure modes (400, 401, 403, 404, 409, 422, 500).
Validate in CI to avoid broken docs on release.
Add server variables to represent environment-specific base URLs if needed.
Consider CORS Configuration for testing via Swagger UI in the browser.
When using gateways (Kong, Apigee), export openapi.json for import and policy Configuration.

Benefits and Use Cases

Where this template shines:

Teams standardizing multiple CFML Microservices: define a consistent contract across apps.
Agencies delivering CF APIs to clients: present a polished, interactive developer portal.
Internal services that rely on Postman/Insomnia for regression tests: generate collections from the spec.
Gateways and proxies: bootstrap policies and documentation by importing openapi.json.
Migration and Modernization efforts: capture legacy CF endpoints into a structured, testable spec.

How it saves time:

Eliminates blank-page syndrome with a ready-made, production-grade skeleton.
Reduces back-and-forth by including examples, pagination, and security out of the box.
Keeps documentation close to code, enabling quick updates and CI/CD validation.

How to Convert YAML to JSON and Vice Versa

Use swagger-cli: npx swagger-cli bundle api-docs/openapi.yaml –outfile api-docs/openapi.json –type json
Or online tools (Swagger Editor, Stoplight Studio) to export in both formats.

Tip: Author in YAML for readability; publish JSON for consumer tools.

Key Takeaways

You get a complete, OpenAPI 3.0.3 template optimized for ColdFusion/Lucee APIs.
It includes Swagger UI, security schemes, reusable components, and CI-ready linting.
Setup is straightforward: place files, wire Swagger UI to openapi.yaml, and validate.
Import the spec into Postman/Insomnia and API Gateways to accelerate testing and Integration.
Treat the spec as an API contract to keep your CFML services consistent and reliable.

FAQ

How do I host Swagger UI without exposing it publicly?

Place /api-docs/swagger-ui/ behind HTTP auth at the web server level (IIS/Apache/Nginx) or restrict access in your ColdFusion routing layer. You can also deploy Swagger UI on a separate admin-only domain.

Can I generate client SDKs from this OpenAPI file?

Yes. Use openapi-generator to produce SDKs in languages like TypeScript, Java, Python, Go, and more. While there’s no native CFML SDK target, your consumers can use the generated clients to integrate quickly.

Does this work with both Adobe ColdFusion and Lucee?

Yes. The template is server-agnostic. You only need to ensure static files are served correctly and add optional CFML routes if you want a dynamic /openapi.json.

How do I keep my spec in sync with code?

Adopt a “spec-first” or “spec-alongside” approach. Update openapi.yaml with every endpoint change, enforce Spectral linting in CI, and require PR reviews that include docs updates.

What if my API uses OAuth2 or JWT?

The template already defines securitySchemes for API Key, Bearer (JWT), and OAuth2. Reference them at the operation level via the security section to indicate which endpoints require which schemes.