Using Swagger UI For Local Development
When working on the swagger documentation, several different tools can be used.
The ‘official’ editor developed by the Swagger community is Swagger Editor, live preview: https://editor.swagger.io/, I have found it quite quick and easy to use, but for larger project it gets cumbersome. Additionally it doesn’t support ability to have multiple files that will reference each other.
This post is a quick demonstration of the workflow I’m using when working on the large, multi-file swagger documentations. It’s certainly not ideal but it helps me to get the job done.
Here it is:
Edit swagger.yaml
This file can be edited in any editor of choice, the yaml
format is widely supported. The documentation can be split up into multiple files that reference each other. I use this functionality to extract examples and other JSON documents. Referencing other files is explained quite well in this post How to split a Swagger spec into smaller files
Publish swagger.yaml
locally
In order to view swagger.yaml
inside Swagger UI the file can be either referenced by a regular file system reference, or it can be fetched via HTTP.
I use local HTTP server to expose swagger.yaml
(with all other, referenced files)
cd ...your_project/swagger
http-server -p 3333 -c-1 --cors
Here I’m using http-server
from npm but you can use any HTTP server, make sure to disable caching and CORS
Run Swagger UI
The last component, Swagger UI can be started like this:
docker run -p 1111:8080 -e API_URL='http://127.0.0.1:3333/swagger.yaml' swaggerapi/swagger-ui
After viewing http://localhost:1111
Swagger UI will display the generated documentation
Now, every time you make a change swagger.yaml
or any file it’s enough to refresh web page to see the changes (or validation errors if there are some)
Summary
This method is more involved that alternatives like Swagger Editor or simply running Swagger UI with file referenced by regular file system reference (possibly outside Docker), but overcomes 2 major limitations of those tools, with it you’ll be able to:
-
Not pollute your environment with different tools when Docker container will work
-
Ability to edit swagger documentation that consist of multiple files (either JSON or YAML)
-
Quick feedback loop, simply refresh web page to see the changes in swagger docs