Using Swagger UI For Local Development

Page content

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