2019-09-13 –, Ferrier Hall
Since all software dev teams are under-resourced, let's see how to get pretty good "living" docs with as little effort as possible. These allow the API to be used directly from the docs. We'll look at a real open source app built with Flask, Swagger and SwaggerUI.
Once upon a time, a non-profit had a website. Not just any website - this website allowed thousands of companies and other non-profits to upload data into it. For this purpose, the website employed some delicious XML processing and a file upload form. For many years, all was seemingly well.
But the non-profit was growing restless - people expected more than needing to login all the time and upload new and changed records. Some of their data partners had many thousands of records which could never be uploaded by hand. So the non-profit sought the (cough) wise counsel of its technical partner Cottage Labs, and ordered the creation of an API.
This is where our journey begins - a team of 3 developers who could only be part-time on this project but had lofty 'live API docs' ambitions. Come and see how they achieved whatever good they managed, and how you could do do better if you were to start upon a similar path today.
Emanuil is a Community Engineer with Elastic, the company behind the open source Elastic Stack (Elasticsearch, APM, Kibana, Beats, and Logstash). He's based in London. He used to be a freelance web developer + ops lead and ran a small open science web dev consultancy with partners for several years. Interested in mentorship, inclusion, small businesses, archery and always curious about how the world works in detail.