So the year 2014 is over and I wrote few posts about books that I enjoyed reading over this period. However, reading IT books about frameworks, processes or practices can be a tiring activity. So once in a while I feel the need to grab a book of a different kind and recently I started reading about the history of our field and also the company side of things – especially startups. In this post I want to offer a short review of books that stood out to me the most and maybe entice you a bit to give them a chance and learn valuable lessons described in them (and there are quite few of them). So without further ado, I present to you my top 3 books of 2014.
I tackled details of integration, documentation creation as well as exposition of documentation using Swagger and its module Swagger UI. One of obvious shortcomings that might be serious concern for people managing their API documentation is fine-grained control over what is published and what stays hidden. There are several reasons to decide to hide something from users. First might be the lack of relevance of introspected information that just don’t belong to the documentation. Other big issue might be security concerns as well as the design of API documentation itself.
One of the first things I have noticed after moving to Dublin was that I managed to arrive just before the start of Web Summit conference. Being so late to the party I decided to take an alternative route and volunteered with my friends to get an inside look at how conference of this magnitude is run and also to meet more like-minded people. Following post is going to provide you a short overview of the event and introduce the atmosphere of biggest IT conference in Europe.
Once you create API documentation it is important to make it available to the stakeholders. In ideal case, this published documentation would be flexible enough to account for any last-minute changes and also be easy to distribute (in terms of costs as well as time needed to accomplish this). To make this possible we will make use of what was accomplished in my previous post detailing the process of creation of API documentation. Using Swagger UI module in combination with published API documentation in json allows us to create simple HTML documentation that may be used to interact with the APIs as well.
The real key to making your REST API easy to use is good documentation. But even if your documentation is done well, you need to set your company processes right to publish it correctly and on time. Ensuring that stakeholders receive it on time is one thing, but you are also responsible for updates in both the API and documentation. Having this process done automatically provides easy way out of trouble, since your documentation is no longer static deliverable and becomes a living thing. In previous post, I discussed how to integrate Swagger with your Spring application with Jersey. Now it’s time to show you how to create documentation and publish it for others to see.