Differences from Swagger #

FLAT uses an enhanced version of Swagger.

x-flat-… Extensions #

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 paths, paths/<path> and paths/<path>/<operation>.
• x-flat-init: init flow (top-level)
• x-flat-error: error flow (top-level)
• x-flat-proxy: proxy configuration (below paths, paths/<path> and paths/<path>/<operation>)
• x-flat-cors: CORS configuration (top-level)
• x-flat-validate: validation (top-level, below paths/<path> and paths/<path>/<operation>)
• x-flat-jwt: expected JWT (in a security scheme object of type apiKey)
• x-flat-cookiename: JWT cookie name
• x-flat-basicauth:: credentials (in a security scheme object of type basic)

Slimline Definition #

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 (get and post) the Swagger specification requires you to write at least:

swagger: "2.0"
info:
  title: ""
  version: "1"
paths:
  /login:
    x-flat-flow: login-flow.xml
    get:
      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 responses sections:

swagger: "2.0"
paths:
  /login:
    x-flat-flow: login-flow.xml
    get:
    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 description or 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.

Example fields #

FLAT allows example fields not only below definitions or schema fields, but also below parameters:

swagger: "2.0"
paths:
  /login:
    post:
      x-flat-flow: login-flow.xml
      parameters:
        - name: username
          in: formData
          type: string
          example: "john.doe" # ←

Wildcard Paths #

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 #

Security schemes can also be applied to specific endpoints, not only to specific operations (HTTP methods) or at top-level.

Specifying scopes in security requirements is FLAT is also allowed for JWT based apiKey security:

paths:
  /:
    x-flat-flow: …
    security:                          # security specific to an endpoint for any operation
      - JWTHeaderAuth: [ write, read ] # ← scopes

securityDefinitions:
  JWTHeaderAuth:
    type: apiKey
    x-flat-jwt:
      …