A minor bug fix for hapi-swagger


Updated 25th December, 2013: The bug fix described below has been merged into the hapi-swagger codebase. The npm package hasn’t yet been updated but I expect it will be in the next few days.

Updated 26th December, 2013: The npm package has now been updated; version 0.0.4 contains this fix.

 

If you’ve recently spent any time at all building a RESTful API using Spumko’s HAPI then it’s more than likely that you’ve come across Swagger. Developed for use on the popular Wordnik site, Swagger is “a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services”. The beauty of the Swagger  approach is that with the hapi-swagger plugin and a few lines of code it’s possible to automatically generate comprehensive, living documentation for your API that is always in sync with your codebase updates… no more excuses for documentation trailing days or weeks behind code changes.

forms_js

Code extract showing the tags used to generate Swagger-based documentation.

 

The Problem

That’s the theory anyway. Unfortunately, there was (and still is) a fairly trivial bug in the hapi-swagger plugin that prevents the documentation being generated as it should.
In the file lib/index.js from line 55 onwards is a small block of code that ensures that Swagger documentation is generated for each defined route:


routes = routes.filter(function (item) {
if (request.query.path &&
item.path.indexOf('/' + request.query.path) !== 0 ) {
return false;
}
return item.settings.plugins['hapi-swagger'] !== false && item.method !== 'options';
 });

What this short snippet of code does is process the routes defined by your app one at a time and selects only those that match a value passed in as request.query.path. For example, if request.query.path equals ‘movies’ then this code will include all routes which begin with the string ‘/movies’. This would mean that we would then generate Swagger formatted documentation for the routes ‘/movies‘, ‘/movies/{id}’, ‘/movies/{id}/actors’ and so on, which is exactly what we want. Unfortunately it would also include routes such as ‘/moviescenes’ which we do not want.

It’s worth mentioning that an earlier version of this code appended an extra “/” symbol to the search string in line 57 so that, instead of ‘/movies’ the route would have to begin with ‘/movies/’. This prevented false positives like ‘/moviescenes’ but, unfortunately, also ignored the top level routes such as ‘/movies’.

The solution

The simplest way to make sure that all the matching routes and only the matching routes generate Swagger documentation is to replace the indexOf in line 57 with a search using a regular expression. With a regular expression, we are able to specify that, for example, only routes which begin ‘/movies/’ be selected (as they were originally) and routes that contain only ‘/movies’. In that way we can make sure we generate documentation for ‘/movies’, ‘/movies/’, ‘/movies/{id}’ and so on, but not ‘/moviescenes’.

The changed code is below (only line 57 has changed):


routes = routes.filter(function (item) {
if (request.query.path &&
item.path.search('^/' + request.query.path + '(/|$)') !== 0 ) {
return false;
}
return item.settings.plugins['hapi-swagger'] !== false && item.method !== 'options';
 });

I have submitted this bug fix to the hapi-swagger repo on Github but if you need it before it is approved and merged (assuming it is accepted) then you can edit the file directly or pull it from my fork of the repo (link below).

I’ve also created a jsFiddle that illustrates the difference between the indexOf approach and the search approach. You can use that to quickly try out some of your own routes.

More:

Validating a MongoDB object id


If you’re working with MongoDB then sooner or later you’re likely to hit an error when inserting or updating a document with a badly constructed Object Id.

For example:


db.mycol.insert({
  "_id": ObjectId("5289e30bcc93743934044d2Z",
  "name": "dvolr"
})

run in the Mongo shell will result in an “Error: invalid object id: not hex” message.

Of course, it’s better to catch this error before even attempting the database update.
This one line Javascript function uses a simple regular expression to check that the id is a 24-character hex string (i.e. only characters 0 to 9 and A to F). It will work in the browser and Node.js.


function isValidObjectID(str) {

  // A valid Object Id must be 24 hex characters
  return (/^[0-9a-fA-F]{24}$/).test(str);

}

// This one returns 'true'
alert( isValidObjectID('507f1f77bcf86cd799439011')

// This one returns false (notice the 'Z')
alert( isValidObjectID('507f1f77bcfZ6cd799439011')

I’ve also created a JSFiddle if you want to try it out with some other values.

More:

Quick Start: MongoDB in less than 60 seconds #2


If you took my advice from the other day and had a look at MongoDB’s excellent Web Shell then you’ve probably tried out a few commands, maybe even worked through a bit of the tutorial. But you’re not only a busy developer, you’re an experienced developer. You know your way around and you don’t want to waste time with superfluous details. You want answers and you want them now. You can handle the truth. In short, what you want is a quick reference guide.

When it comes to quick reference guides I have 2 requirements (apart from the content being half decent):

  1. They must be printable on regular sized (A4) paper.
    This makes PDF my preferred format.
    As a bonus, this also makes them easy to store, search and annotate in Evernote.
  2. They must be readable.
    I’m too old to be squinting at an illegible, 8 point font.

So, bearing those criteria in mind, here are the best of the free MongoDB quick reference guides:

Previously:

Level Up! MongoDB presentation slides


These are the slides from a 60-minute presentation I gave at CFCAMP in Munich, Germany on 15th October, 2013.

The blurb for the presentation was: “The new generation of NoSQL databases offer unprecedented flexibility and ease-of-use when compared to their more traditional, relational rivals. Discover how adding the powerful features of market-leading NoSQL database MongoDB to your skill set can make your ColdFusion development both more productive and more enjoyable.”

The presentation was made to a group of ColdFusion developers with little to no experience of MongoDB or any other NoSQL database.
After a brief introduction to MongoDB, the product and company, the emphasis was on the practicalities of using MongoDB to perform the everyday CRUD (Create, Retrieve, Update, Delete) operations.

A lot of these slides will not make much sense without the talk to go with them but there you go – it was a presentation not a book reading.

As may be apparent, I am a developer not a designer.

Previously:

Quick Start: MongoDB in less than 60 seconds #1


If you’re keen to try out MongoDB but don’t have the time (< 5 minutes) or the permissions to install it on your desktop or server then the MongoDB Web Shell may just be what you’ve been looking for.

MongoDB Web Shell

MongoDB Web Shell in action

Built to emulate the Shell app that ships with MongoDB, the Web Shell is a simple-to-use, free, web-based tool that gives you access to a subset of the full list of shell commands. Yes, your session (and data) is lost when you leave the site but if all you want is a sandbox where you can quickly and easily try out some commands this the place for you.

Bonus: it also comes with a basic tutorial for beginners and some help text.

More:

Level Up! 8 resources for a developer getting started with MongoDB


At the end of my presentation at CFCAMP 2013 I mention a number of resources for ColdFusion developers that can accelerate their understanding and adoption of MongoDB. Below are the 8 most useful of these resources.

If you…

1. Buy only one book

MongoDB: The Definitive Guide (2nd Edition)
Kristina Chodorow
(Oreilly, May 2013)
http://shop.oreilly.com/product/0636920028031.do

2. Read only one ‘getting started’ tutorial

Getting Started with MongoDB by Mathew Setter
Part 1: http://net.tutsplus.com/tutorials/databases/getting-started-with-mongodb
Part 2: http://net.tutsplus.com/tutorials/databases/getting-started-with-mongodb-part-2

These tutorials were written in early 2012 so they don’t cover all of the latest features (such as the Aggregation Framework) but they are still an excellent resource for any experienced developer who just needs a quick introduction to MongoDB CRUD operations.

3. Take only one online course

M101JS: MongoDB for Node.js Developers
MongoDB University
https://education.mongodb.com/courses/10gen/M101JS/2013_October/about

MongoDB Inc (formerly 10Gen) offer a number of excellent, and free, online courses for developers. These typically last 7 weeks with each week covering a different aspect of Mongo. A certificate is awarded on successful completion of the course homework and final exam (currently around 20% of students pass).

There are other developer courses offered using Python or Java but the real focus is on MongoDB so knowledge of the language is not as important as it might appear. Each course gives a brief introduction to the language being used so this is also a good opportunity to get to know Node.js.

4. Follow only one Twitter feed

@mongodbinc

The official Twitter feed of MongoDB, Inc.

5. Join only one Google+ community

MongoDB

6. Subscribe to only one email newsletter

MongoDB News

My own email newsletter, dedicated to bringing developers a comprehensive round-up of the best apps, tools, blog posts, tutorials and resources.

The first issue will be mailed out on Monday, 4th of November, 2013 and then every two weeks thereafter.

7. Use only one Cloud hosted environment for your MongoDB database

MongoHQ

Easy to set up, fast, reliable and with a free tier that is more than suitable for development work and experimenting.

8. Use only one third-party driver to connect ColdFusion to MongoDB

CFMongoDB

This open source driver for ColdFusion is a wrapper to the official MongoDB Inc Java driver and actively maintained.