Merge 0507a2a into 37ee864

README.md

@@ -641,6 +641,12 @@ swagger = Swagger(app)
 
 ```
 
+# OpenAPI 3.0 Support
+
+There is experimental support for OpenAPI 3.0 that should work when using SwaggerUI 3. To use OpenAPI 3.0, set `app.config['SWAGGER']['openapi']` to a version that the current SwaggerUI 3 supports such as `'3.0.2'`.
+
+For an example of this that uses `callbacks` and `requestBody`, see the [callbacks example](examples/callbacks.py).
+
 ## Externally loading Swagger UI and jQuery JS/CSS
 
 Starting with Flasgger 0.9.2 you can specify external URL locations for loading the JavaScript and CSS for the Swagger and jQuery libraries loaded in the Flasgger default templates.  If the configuration properties below are omitted, Flasgger will serve static versions it includes - these versions may be older than the current Swagger UI v2 or v3 releases.

examples/callbacks.py

@@ -0,0 +1,69 @@
+"""
+The simple example using OpenAPI 3.0 callbacks
+"""
+
+from flask import Flask, jsonify
+
+from flasgger import Swagger
+
+app = Flask(__name__)
+app.config['SWAGGER'] = {
+    'title': 'OA3 Callbacks',
+    'openapi': '3.0.2'
+}
+Swagger(app)
+
+
+@app.route('/run_callback/',  methods=['POST'])
+def run_callback():
+    """Example endpoint that specifies OA3 callbacks
+    This is using docstring for specifications
+    ---
+    tags:
+      - callbacks
+    requestBody:
+      description: Test
+      required: true
+      content:
+        application/json:
+          schema:
+            properties:
+              callback_url:
+                type: string
+                format: uri
+                description: Callback URL for request
+    callbacks:
+        onSomeEvent:
+          '{$request.body.callback_url}':
+            post:
+              requestBody:
+                description: status payload
+                content:
+                  application/json:
+                    schema:
+                      properties:
+                        status:
+                          type: string
+    """
+
+    return jsonify({'result': 'ok'})
+
+
+def test_swag(client, specs_data):
+    """
+    This test is runs automatically in Travis CI
+
+    :param client: Flask app test client
+    :param specs_data: {'url': {swag_specs}} for every spec in app
+    """
+    for url, spec in specs_data.items():
+        assert 'openapi' in spec
+        assert spec['openapi'] == '3.0.2'
+
+        assert 'callbacks' in spec['paths']['/run_callback/']['post']
+        assert 'onSomeEvent' in \
+               spec['paths']['/run_callback/']['post']['callbacks']
+
+
+if __name__ == "__main__":
+    app.run(debug=True)

flasgger/base.py

@@ -379,6 +379,19 @@ def get_apispecs(self, endpoint='apispec_1'):
                         prefix_ids=prefix_ids
                     )
 
+                callbacks = swag.get("callbacks", {})
+                if callbacks:
+                    callbacks = {
+                        str(key): value
+                        for key, value in callbacks.items()
+                    }
+                    extract_definitions(
+                        list(callbacks.values()),
+                        endpoint=rule.endpoint,
+                        verb=verb,
+                        prefix_ids=prefix_ids
+                    )
+
                 responses = None
                 if 'responses' in swag:
                     responses = swag.get('responses', {})
@@ -408,6 +421,8 @@ def get_apispecs(self, endpoint='apispec_1'):
                     operation['description'] = swag.get('description')
                 if request_body:
                     operation['requestBody'] = request_body
+                if callbacks:
+                    operation['callbacks'] = callbacks
                 if responses:
                     operation['responses'] = responses
                 # parameters - swagger ui dislikes empty parameter lists