CKAN Swagger UX

Interactive API explorer for any CKAN DataStore resource

Paste any CKAN resource page URL. The DataStore API will be introspected automatically.

Authentication (optional)

Credentials are sent directly to the CKAN instance via Basic Auth headers. They are never stored or transmitted to this service.

Integration Guide

Add a link to your CKAN resource template to launch the explorer directly:

1. Link from your CKAN instance

<a href="https://ckan-swagger.regexflow.com/?url=https://your-ckan.org/dataset/{{ pkg.name }}/resource/{{ res.id }}"
   target="_blank" rel="noopener">
  API Explorer
</a>

2. CORS Configuration (optional, recommended)

The explorer works out of the box via a built-in proxy. For best performance, you can optionally allow direct browser requests by adding to your ckan.ini:

# Option A: Allow all origins (common for public data portals)
ckan.cors.origin_allow_all = true

# Option B: Allow specific origins
ckan.cors.origin_whitelist = https://ckan-swagger.regexflow.com

Without this, requests route through our CORS proxy automatically — fully functional, just slightly slower.

3. Embed as an iframe (optional)

<iframe src="https://ckan-swagger.regexflow.com/?url=https://your-ckan.org/dataset/name/resource/uuid"
        width="100%" height="800" frameborder="0"></iframe>

About CKAN Swagger UX

CKAN Swagger UX is a lightweight, open-source tool that dynamically generates interactive API documentation for any CKAN DataStore resource. Each session introspects the live schema, so changes to fields, types, or data are reflected immediately.

How it works

  • Paste a CKAN resource URL or link directly via query parameter
  • The tool calls the DataStore API to discover the schema — field names, types, enums, and value ranges
  • An OpenAPI 3.1 specification is generated on-the-fly with typed parameters, enum dropdowns, and range hints
  • Users can execute queries directly from the browser — no code required

Architecture

  • Static HTML/JS served from an nginx container (~2MB image)
  • No server-side code, no database, no state
  • A minimal CORS proxy routes only two DataStore endpoints (datastore_search and datastore_search_sql) — all other paths are blocked
  • Per-domain configuration via a JSON config file — editable without rebuilding
  • Internal or system fields (e.g. _id, soda_hashbyte) can be hidden per domain, keeping the API explorer clean for end users

Security measures

  • All CKAN-derived content is sanitised before rendering (XSS prevention)
  • SQL identifiers are escaped using PostgreSQL double-quote rules (injection prevention)
  • URLs validated: HTTPS-only, private IP ranges rejected, no embedded credentials accepted
  • Content Security Policy, X-Content-Type-Options, and X-Frame-Options headers on all responses
  • Container runs as a non-root user
  • Credentials are sent directly to the CKAN instance via Basic Auth — never stored or transmitted to this service
  • CORS proxy restricted to two specific API paths; target must be HTTPS