How to easily edit a Swagger/OpenAPI API specification using free tools
By: +David Herron; Date: June 15, 2017
The Swagger Editor
The Swagger Editor ( http://swagger.io/swagger-editor/) is very cool. As you edit an OpenAPI specification, it interactively verifies the code and gives you errors and warnings, while showing you a very nice constantly updated summary of the API you're creating. With it you can easily explore what you've done, and directly determine if your intent is matched by the code.
It's possible to run the Editor online with no setup on your part at http://editor.swagger.io/
The image above shows the online Editor browsing the Petstore sample application.
To edit your own API specification you must first import the specification file. It supports importing either from a local file, or from a URL. Once you're done editing comes a problem - incorporating the specification file back into your project area. You can Download the new specification as either YAML or JSON. If the specification was in a remote location such as a Github repository, you then have the problem of updating that repository. If the specification was in a local file, you have to ensure the download overwrites that local file.
In other words, using the Swagger Editor is not entirely satisfying. That's because it's running as a web application giving indirect access to files. If it were an Electron app it could just access local files and have the same excellent behavior.
Installing the Swagger Editor locally
You can install the Editor locally but the user experience is about the same.
The documentation for this on the Swagger website is unclear, to say the best. The simplest way is:
- Go to the Swagger Editor Github repository at https://github.com/swagger-api/swagger-editor
- Go to the Releases tab at https://github.com/swagger-api/swagger-editor/releases
- Download the latest release, and unpack it in your filesystem
- In the unpacked directory structure is a file,
You'll be treated with exactly the same user experience as above. The editor is excellent, as is the instant feedback as to the API design. But, since it's exactly the same Editor, you have the exact same clumsiness as to updating the file after editing.
There is also an npm package for Swagger Editor at
https://www.npmjs.com/package/swagger-editor ... it claims you can
npm install swagger-editor and then do
npm start. To do that you must change directory to
node_modules/swagger-editor and then run
npm start, but that failed because one of the dependencies does not support Node 6.x. Or, you can then open
node_modules/swagger-editor/dist/index.html in Firefox, for exactly the same experience as having downloaded a release from the Github repository. Why not just download the Release from the Github repository instead?
Editing an OpenAPI/Swagger specification in Atom
There are probably other editors directly supporting Swagger specifications. I happen to live inside the Atom editor ( https://atom.io) and therefore was happy to learn it's easy to edit a Swagger file in Atom.
What you do is open up the Atom Preferences, and navigate to the Install tab. This is where you install Atom Packages. Note there is another tab for installed Packages.
In the Install tab, enter "swagger" in the search box. The results will include a package named
linter-swagger and another for
linter-swagger-improved. The second package says that
linter-swagger has now been improved and that we should use
linter-swagger instead. So, install
linter-swagger and while you're at it perhaps install
linter since it seems to be pretty darn useful.
Once you've done that, you can edit an OpenAPI specification directly in Atom. It will interactively warn of problems with the code. That's great, and it's just as useful as in the Swagger Editor. But, it doesn't have that nice browsing of the API like you get in Swagger Editor.
The advantage is that you're in a real programmers editor, with direct access to files on your filesystem. The normal coders workflow is then fully available - edit, save, recompile, test, etc.
Swagger UI ( http://swagger.io/swagger-ui/) is another tool that's useful. It parses the API, letting you browse the specification in a web browser.
The installation process is similar to the local install of the Swagger Editor.
- Go to https://github.com/swagger-api/swagger-ui
- Go to https://github.com/swagger-api/swagger-ui/releases
- Download the latest release, and unpack the downloaded archive
- In the resulting directory, open the