Documentation/fix swagger (#4622)

Documentation/Scripts/generateMdFiles.py

@@ -120,7 +120,7 @@ def getRestDescription():
     #print >>sys.stderr, "RESTDESCRIPTION"
     if thisVerb['description']:
         #print >> sys.stderr, thisVerb['description']
-        return thisVerb['description']
+        return RX3[0].sub(RX3[1], thisVerb['description'])
     else:
         #print >> sys.stderr, "ELSE"
         return ""
@@ -254,6 +254,7 @@ RX2 = [
     (re.compile(r"@RESTRETURNCODE{(.*)}"), r"* *\g<1>*:")
 ]
 
+RX3 = (re.compile(r'\*\*Example:\*\*((?:.|\n)*?)</code></pre>'), r"")
 
 match_RESTHEADER = re.compile(r"@RESTHEADER\{(.*)\}")
 match_RESTRETURNCODE = re.compile(r"@RESTRETURNCODE\{(.*)\}")

utils/generateSwagger.py

@@ -552,7 +552,7 @@ def restheader(cargo, r=Regexen()):
         'x-filename': fn,
         'x-examples': [],
         'tags': [currentTag],
-        'summary': summary,
+        'summary': summary.strip(),
         'description': '',
         'parameters' : [],
         }
@@ -1254,6 +1254,10 @@ for name, filenames in sorted(files.items(), key=operator.itemgetter(0)):
         currentDocuBlock = None
         lastDocuBlock = None
 
+# Sort arrays by offset helper:
+def descOffsetGet(value):
+    return value["descOffset"]
+
 for route in swagger['paths'].keys():
     for verb in swagger['paths'][route].keys():
         offsetPlus = 0;
@@ -1263,31 +1267,53 @@ for route in swagger['paths'].keys():
             print >> sys.stderr, "in :" + verb + " " + route
             #raise TODO
         # insert the post json description into the place we extracted it:
+        # Collect the blocks we want to work on, sort them by replacement place:
+        sortVec = []
         for nParam in range(0, len(thisVerb['parameters'])):
             if thisVerb['parameters'][nParam]['in'] == 'body':
+                sortVec.append({
+                    "nParam": nParam,
+                    "descOffset": thisVerb['parameters'][nParam]['x-description-offset']
+                })
+
+        sortVec.sort(key=descOffsetGet)
+        for oneItem in sortVec:
+            nParam = oneItem["nParam"]
             descOffset = thisVerb['parameters'][nParam]['x-description-offset']
             addText = ''
             postText = ''
-                paramDesc = thisVerb['description'][:descOffset]
+            paramDesc = thisVerb['description'][:(descOffset+offsetPlus)]
             if len(paramDesc) > 0: 
                 postText += paramDesc
             if 'additionalProperties' not in thisVerb['parameters'][nParam]['schema']:
                 addText = "\n" + unwrapPostJson(getReference(thisVerb['parameters'][nParam]['schema'], route, verb),1) + "\n\n"
             
             postText += addText
-                postText += thisVerb['description'][descOffset:]
+            postText += thisVerb['description'][(offsetPlus+descOffset):]
             offsetPlus += len(addText)
             thisVerb['description'] = postText
 
+        
         # insert the reply json description into the place we extracted it:
         if 'responses' in thisVerb:
+
+            # Collect the blocks we want to work on, sort them by replacement place:
+            sortVec = []
             for nRC in thisVerb['responses']:
                 if 'x-description-offset' in thisVerb['responses'][nRC]:
+                    sortVec.append({
+                        "nParam": nRC,
+                        "descOffset": thisVerb['responses'][nRC]['x-description-offset']
+                    })
+
+	    sortVec.sort(key=descOffsetGet)
+            for oneItem in sortVec:
+                nRC = oneItem["nParam"]
                 descOffset = thisVerb['responses'][nRC]['x-description-offset']
                 #print descOffset 
                 #print offsetPlus
                 descOffset += offsetPlus
-                    addText = '\n## HTTP ' + nRC
+                addText = '\n#### HTTP ' + nRC
                 #print thisVerb['responses'][nRC]['description']
                 postText = thisVerb['description'][:descOffset]
                 #print postText