From ac799405acefc7bff4592beb92c6ca3064b9910c Mon Sep 17 00:00:00 2001
From: Mirco Nasuti <mirco.nasuti@chuv.ch>
Date: Wed, 20 Jan 2016 09:36:04 +0100
Subject: [PATCH] add maintenance instructions into README

---
 README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/README.md b/README.md
index b470b055b..c2748b1b7 100644
--- a/README.md
+++ b/README.md
@@ -17,3 +17,11 @@ The API documentation is available at `<BASE URL>/swagger-ui.html`. A JSON versi
 * Sync backend with hand written Swagger specs;
 * Implement logout;
 * Update frontend (add introduction page, hide header/footer when not logged in, remove mock authors).
+
+### Maintenance
+
+* To keep an updated API documentation, the developers should keep synchronized both the auto-generated swagger file (from Java annotations) with the hand written one. You can follow this method to get a YAML description from the Java-annotated code:
+  * Add annotations to the Java code;
+  * Get JSON from `<BASE URL>/v2/api-docs`;
+  * Convert JSON to YAML on [http://jsontoyaml.com](http://jsontoyaml.com).
+  
\ No newline at end of file
-- 
GitLab