Using Swagger UI for API Documentation
Last updated
Was this helpful?
master
Last updated
Was this helpful?
FLAT uses 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:
(The docker command won't produce any output when you start it.)
Now, point your browser to 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.
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:
The host must point to the your FLAT server. flat start defaults to localhost:8080. Don't forget to set the http scheme.
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:
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.
Now, Swagger UI can create API requests for you. But your browser won't be allowed to fetch those URLs because of restrictions.