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