Having been lucky enough to pair program with quite a few senior and experienced developers throughout my relatively short programming career the thing that always sticks out to me is how efficient they are moving around their IDE and writing code.
I have been working for a while on improving my typing speed and learning shortcuts and tools to improve my efficiency when coding. I still have a lot to learn, but I recently found one method that helped me with a particularly tedious bit of programming involving an OpenAPI specification.
OpenAPI Generator and Specification Files
I just spent 3 months in the Developer Evangelist team at Xero, and one of the things I did during my time in the team was work on new documentation for the Xero SDKs (Software Development Kits), which developers use to integrate with the Xero API and create marketplace apps. (Xero just reached an awesome milestone of 1000+ connected apps in the ecosystem.)
The Xero SDKs are generated from a YAML file called an OpenAPI Specification, which is a human and computer readable description of the RESTful Xero Public API, using Swagger Codegen.
Using the same generator that is used to generate the SDKs (with a little bit of extra work creating an extra .mustache file for each flavour of the SDKs), we can also generate a HTML file with runnable code samples for all methods available in the SDKs, for each particular API set.
This is a huge improvement over the old docs, which was just some manually created example code for a handful for the API methods.
The generator is pretty smart and does an awesome job taking in the OpenAPI specification together with the mustache templates and spitting out working examples for most of the GET methods of the SDKs. But because the SDKs in each of the languages we support (Java, php, Node, Ruby, NetStandard, Python) have different syntax and naming conventions it is necessary to add in some extra metadata called x-examples in the YAML file in order to handle the more complex tasks like object creation required for update and create methods. This includes adding in ‘keys’ (object or variable names) in different casing (PascalCase, snake_case, and camelCase), enums which have different conventions in different languages, different DateTime formats etc.
When I joined the team the specification for Xero’s Accounting API already had x-examples, but I soon found myself adding in x-examples for each create and update method in the remaining SDKs. (Of which there are many.) Some only had a few methods (the Files API specification only had 6 create or update methods) so while the typing was tedious it was bearable, but I soon moved onto the bigger Payroll APIs and found myself getting frustrated with the amount of times I was typing the same thing. (Each of the Payroll API specifications ended up with over 1000 lines of code additions.)
I experimented with a few different methods to try to speed things up — mostly various combinations of copy and pasting and manually typing, or copying the key a few times and fixing the different casing and values. But it was very tedious work either way and prone to errors. This is when I thought I am sure there has to be an easier way to do this.
Snippets are templates that help developers quickly write repeating code patterns. One of the first snippets I learnt early on in my .NET career (thanks to my little brother Artur for teaching me this one) was the foreach + tab + tab snippet in Visual Studio.
These snippets can speed up development and make things easier when typing common patterns like loops. But there wasn’t any snippets available that would give me the unique structure I needed for the OpenAPI specification x-examples. Luckily VSCode gives us the option to create custom code snippets, so I read up on the documentation and in just a few minutes I was able to create a very simple snippet which copied in the basic key structure I needed, and then navigated my cursor to each next Tabstop so that I can enter in the correct value.
While this snippet was useful and helped me a little, I had only used it a couple of times before I wondered if there was a way to automate the casing conversion, as this was one of the most tedious parts of the process and one that I didn’t overcome with my first snippet. Luckily I found that snippets allow variable transforms in snippets that match parts of a string into groups, and we can then use a format string to format those groups and make simple modifications such as changing the case. There was already an option for changing from snake_case to PascalCase out of the box, and for camelCase I was able to write some simple regex to match and transform the casing. So now I could already press one key character to use my snippet and type the key once, instead of typing a whole structure over and over and writing the same key 4 times in various cases.
By this stage I started to go a bit snippet crazy and started writing small snippets for most of the other attributes we use in x-examples, for things like GUIDs and Lists. The List snippet was probably the biggest time saver as the amount of typing was a bit crazy without it, and I would always have to go back to a previous example and make sure I’m following the same patterns and make sure I haven’t missed something.
Just with this one snippet use, I turned what would otherwise have been 350 keypresses into just 9.
By the time I had all my snippets created, I felt like a magician and what once was a tedious and repetitive task became a bit of fun and also pretty quick. It not only saved me a heap of time and sanity but also reduced the amount of typos and syntax errors, and made the whole process so much simpler.
I hope this post encourages you to go and write your own custom snippets next time you find yourself typing repeating code a bit too often.
Check out the documentation for VSCode snippets if you’d like to know more details on how to write your own snippets, and you can check out the snippets I created here. If you’re interesting in contributing to the Xero SDKs (they are all open source) check out the Xero API GitHub.
Lastly, check out the Xero Developer portal if you are interested in partnering with Xero and joining the 1000+ apps on the marketplace!