Merge pull request #50 from olivier-heurtier/json-example

Get example from the schema when available

Author: ikalnytskyi

sphinxcontrib/openapi/openapi30.py

@@ -179,6 +179,10 @@ def _example(media_type_objects, method=None, endpoint=None, status=None,
         examples = content.get('examples')
         example = content.get('example')
 
+        # Try to get the example from the schema
+        if example is None and 'schema' in content:
+            example = content['schema'].get('example')
+
         if examples is None:
             examples = {}
             if not example:
@@ -198,6 +202,7 @@ def _example(media_type_objects, method=None, endpoint=None, status=None,
                 }
 
         for example in examples.values():
+            # According to OpenAPI v3 specs, string examples should be left unchanged
             if not isinstance(example['value'], str):
                 example['value'] = json.dumps(
                     example['value'], indent=4, separators=(',', ': '))

tests/test_openapi.py

@@ -1529,6 +1529,127 @@ def test_callback(self):
 
         ''').lstrip()
 
+    def test_string_example(self):
+        renderer = renderers.HttpdomainOldRenderer(None, {'examples': True})
+        text = '\n'.join(renderer.render_restructuredtext_markup({
+            'openapi': '3.0.0',
+            'paths': {
+                '/resources': {
+                    'get': {
+                        'summary': 'Get resources',
+                        'responses': {
+                            '200': {
+                                'description': 'Something',
+                                'content': {
+                                    'application/json': {
+                                        'schema': {
+                                            'type': 'string',
+                                            'example': '"A sample"',
+                                        }
+                                    }
+                                }
+                            },
+                        },
+                    },
+                },
+            },
+        }))
+
+        assert text == textwrap.dedent('''
+            .. http:get:: /resources
+               :synopsis: Get resources
+
+               **Get resources**
+
+
+               **Example request:**
+
+               .. sourcecode:: http
+
+                  GET /resources HTTP/1.1
+                  Host: example.com
+
+               :status 200:
+                  Something
+
+                  **Example response:**
+
+                  .. sourcecode:: http
+
+                     HTTP/1.1 200 OK
+                     Content-Type: application/json
+
+                     "A sample"
+
+        ''').lstrip()
+
+    def test_ref_example(self):
+        renderer = renderers.HttpdomainOldRenderer(None, {'examples': True})
+        text = '\n'.join(renderer.render_restructuredtext_markup({
+            'openapi': '3.0.0',
+            'paths': {
+                '/resources': {
+                    'get': {
+                        'summary': 'Get resources',
+                        'responses': {
+                            '200': {
+                                'description': 'Something',
+                                'content': {
+                                    'application/json': {
+                                        'schema': {
+                                            '$ref':
+                                                '#/components/schemas/Data',
+                                        }
+                                    }
+                                }
+                            },
+                        },
+                    },
+                },
+            },
+            'components': {
+                'schemas': {
+                    'Data': {
+                        'type': 'object',
+                        'additionalProperties': True,
+                        'example': {
+                            'prop1': "Sample 1",
+                        }
+                    }
+                }
+            }
+        }))
+
+        assert text == textwrap.dedent('''
+            .. http:get:: /resources
+               :synopsis: Get resources
+
+               **Get resources**
+
+
+               **Example request:**
+
+               .. sourcecode:: http
+
+                  GET /resources HTTP/1.1
+                  Host: example.com
+
+               :status 200:
+                  Something
+
+                  **Example response:**
+
+                  .. sourcecode:: http
+
+                     HTTP/1.1 200 OK
+                     Content-Type: application/json
+
+                     {
+                         "prop1": "Sample 1"
+                     }
+
+        ''').lstrip()
+
     def test_method_option(self):
         spec = collections.defaultdict(collections.OrderedDict)
         spec['paths']['/resource_a'] = {