Documenting lists with Swagger

Swagger is a great tool for documenting APIs.  Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation.

We use Swagger a lot at work.  We’ve even pushed the bar slightly, but automatically generating the API documentation on the fly, to match the rest of our Qobrix functionality.  Whenever you change the database schema or the configuration of the fields, the changes are also reflected immediately in the API documentation.  And it works great!

One of the things that we haven’t done though until very recently is the documentation of the list fields.  Swagger provides the enum to document the values that can go into the field, but it’s not very helpful, when the values are not obvious.  Country codes and currency symbols work well, as they are common knowledge.  But if you have something custom, there needs to be a set of labels associated with the set of values.

The other day we decided that something is better than nothing, and added the documentation of the values as part of the field description (the property is described on the same page as enum above).  Here’s the Pull Request with the tiniest of changes.  And here’s how it looks in Swagger:

I admit, it’s not the prettiest of things, but at least the hints for the developers are there.  Also, since the list of labels uses a specific format, it’s quite easy to parse it out of the Swagger JSON automatically and reuse in third-party applications and services (like a website, connected to the system via the API).

While browsing around, I’ve also noticed that Swagger is growing and expanding. There is a new version of the specification – version 3.0, which has also been re-branded as OpenAPI Specification (see OpenAPI Initiative).  Here’s a great blog post that describes the differences between this and the previous versions, and here’s the migration guide for those who need it.

If you are working with PHP, zircote/swagger-php is the way to go.  It already even support the version 3.0.  If you are using the CakePHP framework, alt3/cakephp-swagger is the plugin for you (version 3.0 is not yet supported, but I’m sure it’ll get there soon).

Bitmask Constant Arguments in PHP

Liam Hammett (check many of his other excellent posts) has a nice explanation of the bitmask constant arguments in PHP.  These are fairly common and most PHP developers have seen them.  However, it’s been a few occasions where I discovered that especially newer developers don’t understand how this works.

Bitmask arguments and operations were used extensively in programming by the older generations, especially where CPU and memory were critical.  But with hardware getting so much cheaper over the last few decades, nobody really cares about an extra few memory bytes and CPU cycles.

Regardless of the memory and CPU though, bitmask arguments are still quite handy and using them can significantly simplify the code.

PHP Safe and Rector

I came across a couple of very interesting PHP libraries today.

The first one is thecodingmachine/safe.  This library wraps all PHP functions that return false on failure into another function that throws the exception instead. Think of all those file_get_contents() and json_decode() situations you had to code around.  Not anymore.  You can easily have them throw exceptions now.  Read this blog post for more details.

The second one is rectorphp/rector.  It is in fact mentioned in the documentation for the above library.  Rector is a refactoring (reconstruction and upgrade) tool that can easily change large chunks of your code.  Think of function renaming, parameter changes, and such.  Read these blog posts for more details: part 1, part 2, and part 3.

Very handy!

PHP assertions and assertion libraries

I’ve blogged about PHP assertions and assertion libraries a while back.  I haven’t started using the assertions anywhere outside of unit tests yet, but with more and more bloat added to the code to check for types and particular values, I keep coming back to the idea.

Today I came across a nice article by Matthias Noback which once again made me consider assertion libraries in my codebase.  I’ll discuss with colleagues and hopefully we’ll make the decision once and for all on whether assertions are a good way to go forward.

7 Tips to Write Exceptions Everyone Will Love

Tomas Votruba shares the “7 Tips to Write Exceptions Everyone Will Love“.  These all make a lot of sense and are generic enough to be applicable to any programming language (that implements exceptions).  The list of tips is as follows:

  1. Make Exception Names for Humans
  2. Use Quotes Around Statements
  3. What Exactly is Wrong?
  4. What is The Wrong Value?
  5. What File Exactly is Broken?
  6. What Options do I have?
  7. Link what You can’t Fit 140 Chars

Read the full article for both good and bad examples, as well as the explanations of the above.

The Alternative Dictionary of Web Design Terms

Webdesigner Depot runs “The Alternative Dictionary of Web Design Terms“.  It’s simple, yet pretty funny and accurate.  I liked all of it, but a few of my favorites are:

  • Agile: A development methodology that advocates self-organizing teams and flexibility, allowing startups to more efficiently realize they’re building something that no one wants.
  • Backlink: Before experimenting with dogs, Pavlov trained online marketers to salivate whenever he said “backlink”. It still works.
  • Code: The stuff they show on computer screens in the less-offensive Hollywood representations of hacking.
  • Comments (in Code): In-jokes and clever insights that only total nerds will ever see. One day, someone will achieve true enlightenment, and the secret will written down as a code comment, and lost to an obscure GitHub repository.
  • Navigation: The quickest and easiest way for a customer to get lost.
  • URL: U R Lost.


Cold War on Ice

Cold War on Ice is an excellent documentary about the USSR vs. Canada ice hockey Summit Series 1972 games.  I find it to be quite balanced, showing the perception from both sides, featuring the interviews with the same people back in the day and their take on it now, and plenty of great footage.

It’s a must see for any ice hockey fan and history nerd.