diff --git a/sphinxcontrib/openapi/openapi30.py b/sphinxcontrib/openapi/openapi30.py index e5bf2d8..43f87b6 100644 --- a/sphinxcontrib/openapi/openapi30.py +++ b/sphinxcontrib/openapi/openapi30.py @@ -261,13 +261,8 @@ def _httpresource(endpoint, method, properties, render_examples): name=param['name']) for line in param.get('description', '').splitlines(): yield '{indent}{indent}{line}'.format(**locals()) - - # print request example - if render_examples: - request_content = properties.get('requestBody', {}).get('content', {}) - for line in _example( - request_content, method, endpoint=endpoint, nb_indent=1): - yield line + if param.get('required', False): + yield '{indent}{indent}(Required)'.format(**locals()) # print response status codes for status, response in responses.items(): @@ -275,17 +270,13 @@ def _httpresource(endpoint, method, properties, render_examples): for line in response['description'].splitlines(): yield '{indent}{indent}{line}'.format(**locals()) - # print response example - if render_examples: - for line in _example( - response.get('content', {}), status=status, nb_indent=2): - yield line - # print request header params for param in filter(lambda p: p['in'] == 'header', parameters): yield indent + ':reqheader {name}:'.format(**param) for line in param.get('description', '').splitlines(): yield '{indent}{indent}{line}'.format(**locals()) + if param.get('required', False): + yield '{indent}{indent}(Required)'.format(**locals()) # print response headers for status, response in responses.items(): @@ -294,6 +285,19 @@ def _httpresource(endpoint, method, properties, render_examples): for line in header['description'].splitlines(): yield '{indent}{indent}{line}'.format(**locals()) + if render_examples: + # print request example + request_content = properties.get('requestBody', {}).get('content', {}) + for line in _example( + request_content, method, endpoint=endpoint, nb_indent=1): + yield line + + # print response example + for status, response in responses.items(): + for line in _example( + response.get('content', {}), status=status, nb_indent=1): + yield line + yield '' diff --git a/tests/test_openapi.py b/tests/test_openapi.py index 8159a05..e6fc8b8 100644 --- a/tests/test_openapi.py +++ b/tests/test_openapi.py @@ -659,24 +659,24 @@ def test_example_generation(self): Show up to `limit` entries. :status 200: An array of resources. + :reqheader If-None-Match: + Last known resource ETag. - **Example response:** + **Example response:** - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - [ - { - "kind": "string", - "description": "string", - "data": "c3RyaW5n" - } - ] + [ + { + "kind": "string", + "description": "string", + "data": "c3RyaW5n" + } + ] - :reqheader If-None-Match: - Last known resource ETag. .. http:post:: /resources/ :synopsis: Create Resource @@ -685,6 +685,8 @@ def test_example_generation(self): ~ some useful description ~ + :status 200: + The created resource. **Example request:** @@ -699,21 +701,19 @@ def test_example_generation(self): "data": "c3RyaW5n" } - :status 200: - The created resource. - **Example response:** + **Example response:** - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "kind": "string", - "description": "string", - "data": "c3RyaW5n" - } + { + "kind": "string", + "description": "string", + "data": "c3RyaW5n" + } .. http:get:: /resources/{kind} @@ -728,18 +728,18 @@ def test_example_generation(self): :status 200: The created resource. - **Example response:** + **Example response:** - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "kind": "string", - "description": "string", - "data": "c3RyaW5n" - } + { + "kind": "string", + "description": "string", + "data": "c3RyaW5n" + } .. http:patch:: /resources/{kind} @@ -751,6 +751,8 @@ def test_example_generation(self): :param string kind: Kind of resource to list. + :status 200: + The created resource. **Example request:** @@ -765,21 +767,19 @@ def test_example_generation(self): "data": "c3RyaW5n" } - :status 200: - The created resource. - **Example response:** + **Example response:** - .. sourcecode:: http + .. sourcecode:: http - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "kind": "string", - "description": "string", - "data": "c3RyaW5n" - } + { + "kind": "string", + "description": "string", + "data": "c3RyaW5n" + } ''').lstrip()