> For the complete documentation index, see [llms.txt](https://sevenval.gitbook.io/flat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sevenval.gitbook.io/flat/cookbook/swagger-docs.md).

# Using Swagger UI for API Documentation

FLAT uses [Swagger/OpenAPI 2.0](https://swagger.io/docs/specification/2-0/basic-structure/) as its API definition format.

One of the advantages of well-known, open standard formats is the tooling provided by the community. Swagger is supported by many tools. One of these is the official Swagger-UI that is available as Docker Image [`swaggerapi/swagger-ui`](https://hub.docker.com/r/swaggerapi/swagger-ui/).

## Documentation

If you want to see a pretty (and interactive!) documentation for you API definition, start the UI server on your local machine like this:

```bash
$ docker run --rm -p 9002:8080 -v $(pwd)/swagger.yml:/swagger.yaml -e SWAGGER_JSON=/swagger.yaml swaggerapi/swagger-ui
```

(The docker command won't produce any output when you start it.)

Now, point your browser to <http://localhost:9002/> and browse your docs!

The command line assumes that you are in your project directory and the API definition is in `./swagger.yml`. If you have a `swagger.json` or any other name, simply change the part *left* of the colon (`:`) in the `-v` argument, such as `-v $(pwd)/swagger.json:/swagger.yaml`.

## Interactive Mode

The Swagger UI features a *Try it out!* function that creates API calls for you. You can either copy and paste the `curl` command lines provided, or even perform the fetch right in the browser.

To make that work, however, you need to have `host` and `scheme` settings in your API definition. Your `swagger.yml` could start like this:

```yaml
swagger: '2.0'
host: localhost:8080
schemes:
- http
basePath: /api
…
```

The `host` must point to the your FLAT server. `flat start` defaults to `localhost:8080`. Don't forget to set the `http` scheme.

Now, Swagger UI can create API requests for you. But your browser won't be allowed to fetch those URLs because of [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) restrictions.

FLAT has a handy feature to make that work! Simply list the URL of your swagger-ui docker container in the `cors` config settings in `/conf/config.xml`:

```markup
<config>
  <flat>
    <definition src="../swagger.yml" />
    <cors allowed-origins="http://localhost:9002" />
  </flat>
</config>
```

Finally, you can *try it out*. FLAT will handle the CORS preflight checks with your browser, and you can perform test requests with the swagger UI.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/cookbook/swagger-docs.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.