How to easily edit a Swagger/OpenAPI API specification using free tools

By: (plus.google.com) +David Herron; Date: June 15, 2017

Tags: OpenAPI » Swagger

The official way to edit a Swagger/OpenAPI document is using the Swagger Editor available through the swagger.io website, or to use the SwaggerHub website. The Editor can be run on your laptop inside a web browser which allows local JavaScript execution. As browsers tighten the screws on security the ability to do that may cease, and I see in the issue queue a request to make Electron versions of the Swagger tools. The SwaggerHub website is another option, especially as it offers lots of interesting features (at a fee). But, since OpenAPI is a free and open specification it's possible for others to develop tools. In this post we'll go over using the Swagger Editor, and using Atom to edit an OpenAPI specification.

The Swagger Editor

The Swagger Editor ( (swagger.io) 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 (editor.swagger.io) 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:

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 (www.npmjs.com) 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 ( (atom.io) 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

Swagger UI ( (swagger.io) 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.

« Displaying text on LCD screen from the Arduino UNO Best implementation of the Swagger UI tool for your OpenAPI based Spring Boot REST server »
2016 Election Acer C720 Ad block AkashaCMS Amazon Amazon Kindle Amiga Android Anti-Fascism Apple Apple Hardware History Apple iPhone Apple iPhone Hardware April 1st Arduino ARM Compilation Astronomy Asynchronous Programming Authoritarianism Automated Social Posting Ayo.JS Bells Law Big Brother Big Finish Black Holes Blade Runner Blogger Blogging Books Botnet Botnets Cassette Tapes Cellphones Christopher Eccleston Chrome Chrome Apps Chromebook Chromebooks Chromebox ChromeOS CIA CitiCards Citizen Journalism Civil Liberties Clinton Cluster Computing Command Line Tools Computer Hardware Computer Repair Computers Cross Compilation Crouton Cryptocurrency Curiosity Rover Cyber Security Cybermen Daleks Darth Vader Data backup Data Storage Database Database Backup Databases David Tenant DDoS Botnet Detect Adblocker Developers Editors Digital Photography DIY DIY Repair DNP3 Docker Doctor Who Doctor Who Paradox Drobo Drupal Drupal Themes DVD E-Books E-Readers Early Computers Election Hacks Electric Bicycles Electric Vehicles Electron Emdebian Energy Efficiency Enterprise Node EPUB ESP8266 Ethical Curation Eurovision Event Driven Asynchronous Express Facebook Fake News Fedora VirtualBox File transfer without iTunes FireFly Fraud Freedom of Speech Gallifrey git Gitlab GMAIL Google Google Chrome Google Gnome Google+ Government Spying Great Britain Heat Loss Hibernate Home Automation HTTPS I2C Protocol Image Analysis Image Conversion Image Processing ImageMagick InfluxDB Infrared Thermometers Insulation Internet Internet Advertising Internet Law Internet of Things Internet Policy Internet Privacy iOS Devices iPad iPhone iPhone hacking Iron Man Iternet of Things iTunes Java JavaScript JavaScript Injection JDBC John Simms Journalism Joyent Kindle Marketplace Lets Encrypt LibreOffice Linux Linux Hints Linux Single Board Computers Logging Mac OS Mac OS X MacOS X setup Make Money Online MariaDB Mars Matt Lucas MEADS Anti-Missile Mercurial Michele Gomez Micro Apartments Military Hardware Minification Minimized CSS Minimized HTML Minimized JavaScript Missy Mobile Applications MODBUS Mondas MongoDB Mongoose Monty Python MQTT Music Player Music Streaming MySQL NanoPi Nardole NASA Net Neutrality Node Web Development Node.js Node.js Database Node.js Testing Node.JS Web Development Node.x North Korea Online advertising Online Fraud Online Journalism Online Video Open Media Vault Open Source Governance Open Source Licenses Open Source Software OpenAPI OpenVPN Personal Flight Peter Capaldi Photography PHP Plex Plex Media Server Political Protest Postal Service Power Control Privacy Production use Public Violence Raspberry Pi Raspberry Pi 3 Raspberry Pi Zero Recycling Remote Desktop Republicans Retro-Technology Reviews Right to Repair River Song Robotics Rocket Ships RSS News Readers rsync Russia Russia Troll Factory SCADA Scheme Science Fiction Search Engine Ranking Season 1 Season 10 Season 11 Security Security Cameras Server-side JavaScript Shell Scripts Silence Simsimi Skype Social Media Warfare Social Networks Software Development Space Flight Space Ship Reuse Space Ships SpaceX Spear Phishing Spring Spring Boot SQLite3 SSD Drives SSD upgrade SSH SSH Key SSL Swagger Synchronizing Files Telescopes Terrorism The Cybermen The Daleks The Master Time-Series Database Torchwood Total Information Awareness Trump Trump Administration Ubuntu UDOO Virtual Private Networks VirtualBox VLC VNC VOIP Web Applications Web Developer Resources Web Development Web Development Tools Web Marketing Website Advertising Weeping Angels WhatsApp Window Insulation Wordpress YouTube YouTube Monetization