FLAT uses Swagger/OpenAPI 2.0 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
If you want to see a pretty (and interactive!) documentation for you API definition, start the UI server on your local machine like this:
$ 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
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
scheme settings in your API definition. Your
swagger.yml could start like this:
swagger: '2.0'host: localhost:8080schemes:- httpbasePath: /api…
host must point to the your FLAT server.
flat start defaults to
localhost:8080. Don't forget to set the
Now, Swagger UI can create API requests for you. But your browser won't be allowed to fetch those URLs because of 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
<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.