Merge pull request #47 from albert2126/RequestBody

Request body is added to rendered docs - see issue #38

.gitignore

@@ -1,6 +1,6 @@
 # Backup files
 *.~
-
+.idea/
 # Byte-compiles / optimizied
 __pycache__/
 *.py[cod]

sphinxcontrib/openapi/directive.py

@@ -67,6 +67,7 @@ class OpenApi(Directive):
     option_spec = {
         'encoding': directives.encoding,    # useful for non-ascii cases :)
         'paths': lambda s: s.split(),       # endpoints to be rendered
+        'request': directives.flag,         # print the request body structure
         'examples': directives.flag,        # render examples when passed
         'group': directives.flag,           # group paths by tag when passed
         'format': str,                      # "rst" (default) or "markdown"

sphinxcontrib/openapi/openapi20.py

@@ -170,6 +170,10 @@ def openapihttpdomain(spec, **options):
         raise ValueError(
             'Rendering examples is not supported for OpenAPI v2.x specs.')
 
+    if 'request' in options:
+        raise ValueError(
+            'The :request: option is not supported for OpenAPI v2.x specs.')
+
     generators = []
 
     # OpenAPI spec may contain JSON references, common properties, etc.

sphinxcontrib/openapi/openapi30.py

@@ -141,7 +141,7 @@ def _example(media_type_objects, method=None, endpoint=None, status=None,
     """
     Format examples in `Media Type Object` openapi v3 to HTTP request or
     HTTP response example.
-    If method and endpoint is provided, this fonction prints a request example
+    If method and endpoint is provided, this function prints a request example
     else status should be provided to print a response example.
 
     Arguments:
@@ -225,7 +225,8 @@ def _example(media_type_objects, method=None, endpoint=None, status=None,
             yield ''
 
 
-def _httpresource(endpoint, method, properties, convert, render_examples):
+def _httpresource(endpoint, method, properties, convert, render_examples,
+                  render_request):
     # https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.0.md#operation-object
     parameters = properties.get('parameters', [])
     responses = properties['responses']
@@ -264,6 +265,22 @@ def _httpresource(endpoint, method, properties, convert, render_examples):
         if param.get('required', False):
             yield '{indent}{indent}(Required)'.format(**locals())
 
+    # print request content
+    if render_request:
+        request_content = properties.get('requestBody', {}).get('content', {})
+        if request_content and 'application/json' in request_content:
+            schema = request_content['application/json']['schema']
+            req_properties = json.dumps(schema['properties'], indent=2,
+                                        separators=(',', ':'))
+            yield '{indent}**Request body:**'.format(**locals())
+            yield ''
+            yield '{indent}.. sourcecode:: json'.format(**locals())
+            yield ''
+            for line in req_properties.splitlines():
+                # yield indent + line
+                yield '{indent}{indent}{line}'.format(**locals())
+                # yield ''
+
     # print request example
     if render_examples:
         request_content = properties.get('requestBody', {}).get('content', {})
@@ -310,7 +327,8 @@ def _httpresource(endpoint, method, properties, convert, render_examples):
                         cb_method,
                         cb_properties,
                         convert=convert,
-                        render_examples=render_examples):
+                        render_examples=render_examples,
+                        render_request=render_request):
                     if line:
                         yield indent+indent+line
                     else:
@@ -344,6 +362,10 @@ def openapihttpdomain(spec, **options):
                 )
             )
 
+    render_request = False
+    if 'request' in options:
+        render_request = True
+
     convert = utils.get_text_converter(options)
 
     # https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.0.md#paths-object
@@ -358,7 +380,8 @@ def openapihttpdomain(spec, **options):
                     method,
                     properties,
                     convert,
-                    render_examples='examples' in options))
+                    render_examples='examples' in options,
+                    render_request=render_request))
 
         for key in sorted(groups.keys()):
             if key:
@@ -375,6 +398,7 @@ def openapihttpdomain(spec, **options):
                     method,
                     properties,
                     convert,
-                    render_examples='examples' in options))
+                    render_examples='examples' in options,
+                    render_request=render_request))
 
     return iter(itertools.chain(*generators))

tests/test_spec_examples.py

@@ -36,6 +36,7 @@ def test_openapi2_success(tmpdir, run_sphinx, spec):
 
 @pytest.mark.parametrize('group_paths', [False, True])
 @pytest.mark.parametrize('render_examples', [False, True])
+@pytest.mark.parametrize('render_request', [False, True])
 @pytest.mark.parametrize('spec', glob.glob(
     os.path.join(
         os.path.abspath(os.path.dirname(__file__)),
@@ -45,9 +46,10 @@ def test_openapi2_success(tmpdir, run_sphinx, spec):
         '*.yaml')
 ))
 def test_openapi3_success(tmpdir, run_sphinx, spec, render_examples,
-                          group_paths):
+                          render_request, group_paths):
     py.path.local(spec).copy(tmpdir.join('src', 'test-spec.yml'))
     run_sphinx('test-spec.yml', options={
         'examples': render_examples,
+        'request': render_request,
         'group': group_paths,
     })