# 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](https://sevenval.gitbook.io/flat/openapi-4/routing#assigning-flat-flows) to be started. Recognized at top-level and below `paths`, `paths/<path>` and `paths/<path>/<operation>`.
* `x-flat-init`: [init flow](https://sevenval.gitbook.io/flat/openapi-4/routing#init-flow) (top-level)
* `x-flat-error`: [error flow](https://sevenval.gitbook.io/flat/openapi-4/routing#error-flow) (top-level)
* `x-flat-proxy`: [proxy configuration](https://sevenval.gitbook.io/flat/openapi-4/routing#assigning-flat-proxies) (below `paths`, `paths/<path>` and `paths/<path>/<operation>`)
* `x-flat-cors`: [CORS configuration](https://sevenval.gitbook.io/flat/reference/openapi-1/cors) (top-level)
* `x-flat-validate`: [validation](https://sevenval.gitbook.io/flat/reference/openapi-7/validation) (top-level, below `paths/<path>` and `paths/<path>/<operation>`)
* `x-flat-jwt`: [expected JWT](https://sevenval.gitbook.io/flat/openapi-5/security#the-x-flat-jwt-field) (in a [security scheme object](https://swagger.io/specification/v2/#securitySchemeObject))
* `x-flat-cookiename`: [JWT cookie name](https://sevenval.gitbook.io/flat/openapi-5/security#jwt-in-cookie)

## 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](https://sevenval.gitbook.io/flat/openapi-4/routing#assigning-flat-flows) to a path with two operations (`get` and `post`) the Swagger specification requires you to write at least:

```yaml
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](https://sevenval.gitbook.io/flat/reference/openapi-7/validation), you may even drop the useless `responses` sections:

```yaml
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:

```yaml
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](https://sevenval.gitbook.io/flat/reference/openapi-7/validation) for requests and responses.

> 📎 Note that [most tools](https://sevenval.gitbook.io/flat/cookbook/swagger-docs) require a complete Swagger definition and may refuse to process FLAT's slimline definitions.

## 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:

```yaml
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](https://sevenval.gitbook.io/flat/openapi-5/security#applying-security-schemes) can also be applied to specific paths, not only to specific operations or top-level.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sevenval.gitbook.io/flat/reference/openapi-2/differences.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.