FLAT uses an enhanced version of Swagger.
First of all, several extensions named
x-flat-… are recognized on different levels of the definition:
x-flat-flow: flow to be started. Recognized at top-level and below
x-flat-init: init flow (top-level)
x-flat-error: error flow (top-level)
x-flat-proxy: proxy configuration (below
x-flat-cors: CORS configuration (top-level)
x-flat-validate: validation (top-level, below
x-flat-cookiename: JWT cookie name
Defining endpoints in
swagger.yaml should be straight-forward. However, typing Swagger compliant YAML or JSON can be somewhat cumbersome. To assign a flow to a path with two operations (
post) the Swagger specification requires you to write at least:
swagger: "2.0"info:title: ""version: "1"paths:/login:x-flat-flow: login-flow.xmlget:responses:default:description: ""post:responses:default:description: ""
In FLAT you may omit the top-level
info section. And as long as you don't need a schema for response validation, you may even drop the useless
swagger: "2.0"paths:/login:x-flat-flow: login-flow.xmlget:post:
If you don't care which HTTP methods are allowed for a path, you may skip specifying the operations entirely:
swagger: "2.0"paths:/login:x-flat-flow: login-flow.xml
It is by no means a bad thing to write a conformant definition and provide a
version information. However, it frequently slows you down unnecessarily and degrades readability. FLAT allows you to quickly define the endpoints of your API and start working with them. Once set up, you can gradually refine them by adding more operations and schemas for requests and responses.
📎 Note that most tools require a complete Swagger definition and may refuse to process FLAT's slimline definitions.
While paths ending with
/** are treated like all other paths in standard Swagger, they are handled specially in FLAT. Such a wildcard path matches any request path having the same prefix and, optionally, arbitrary additional segments. "Normal" paths without a trailing wildcard pattern
/** are always matched first:
swagger: "2.0"paths:/foo:# matches /foo/foo/bar/**:# matches /foo/bar, /foo/bar/…, /foo/bar/…/…, etc., e.g. /foo/bar/1# but not e.g. /foo/bar1/foo/**:# matches /foo/…, /foo/…/…, etc., e.g. /foo/qux/**:# matches everything else, e.g. /bar
The longest matching wildcard path wins. The position of a wildcard path in the definition is irrelevant.
Note that path parameters (i.e. sections enclosed in curly braces) cannot be combined with wildcards.
Security schemes can also be applied to specific paths, not only to specific operations or top-level.