doc(headers): handle headers in swagger doc (#274)

build_openapi.py

@@ -95,6 +95,20 @@ def translate_to_swag(doc, subs):
         ]
     )
 
+    # Headers
+    args = doc.get("Headers")
+    spec["parameters"].extend(
+        [
+            {
+                "in": "header",
+                "name": name,
+                "type": swagger_types.get(props.type, props.type),
+                "description": props.description,
+            }
+            for name, props in args.iteritems()
+        ]
+    )
+
     # handle substitutions
     for p in spec["parameters"]:
         for k, v in subs.iteritems():

openapi/docstring_parser.py

@@ -8,7 +8,7 @@ class Argument(object):
         name (type): description
     """
 
-    re_arg = re.compile(r"([\w_]+)(?: \(([\w_]+)\))?: ([\w\s_.,;:'\"`()|]+)")
+    re_arg = re.compile(r"([\w_-]+)(?: \(([\w_]+)\))?: ([\w\s_.,;:'\"`()|/-]+)")
     #                     ^ name        ^ type        ^ description
 
     def __init__(self, name=None, arg_type=None, description=None):
@@ -40,7 +40,7 @@ class Docstring(object):
     Store docstring arguments by section.
     """
 
-    section_names = ["Args", "Query Args", "Responses", "Summary", "Tags"]
+    section_names = ["Args", "Query Args", "Headers", "Responses", "Summary", "Tags"]
     single_arg_section_names = ["Summary", "Tags"]
 
     def __init__(self):
@@ -75,6 +75,7 @@ def parse_section(cls, section, docstring):
             pass
 
         args = map(Argument.from_string, filter(bool, section_args.split("\n")))
+
         if section in cls.single_arg_section_names:
             return args
         else:

openapi/swagger.yml

@@ -324,6 +324,11 @@ paths:
         name: body
         schema:
           $ref: '#/definitions/schema_entity'
+      - description: application/json (default), text/tab-separated-values, text/tsv
+          or text/csv
+        in: header
+        name: Content-Type
+        type: string
       responses:
         '201':
           description: Entities created successfully
@@ -356,6 +361,11 @@ paths:
         name: body
         schema:
           $ref: '#/definitions/schema_entity'
+      - description: application/json (default), text/tab-separated-values, text/tsv
+          or text/csv
+        in: header
+        name: Content-Type
+        type: string
       responses:
         '201':
           description: Entities created successfully
@@ -448,6 +458,11 @@ paths:
         name: body
         schema:
           $ref: '#/definitions/schema_entity'
+      - description: application/json (default), text/tab-separated-values, text/tsv
+          or text/csv
+        in: header
+        name: Content-Type
+        type: string
       responses:
         '201':
           description: Entities created successfully
@@ -480,6 +495,11 @@ paths:
         name: body
         schema:
           $ref: '#/definitions/schema_entity'
+      - description: application/json (default), text/tab-separated-values, text/tsv
+          or text/csv
+        in: header
+        name: Content-Type
+        type: string
       responses:
         '201':
           description: Entities created successfully
@@ -625,7 +645,7 @@ paths:
         name: project
         required: true
         type: string
-      - description: A comma
+      - description: A comma-separated list of ids specifying the entities to retrieve.
         in: path
         name: entity_id_string
         required: true

sheepdog/blueprint/routes/views/program/project.py

@@ -63,6 +63,9 @@ def create_entities(program, project):
             project (str): |project_id|
             body (schema_entity): input body
 
+        Headers:
+            Content-Type (str): application/json (default), text/tab-separated-values, text/tsv or text/csv
+
         Responses:
             201: Entities created successfully
             404: Resource not found.