squashed: oas3 docs and support for multiple servers in oas3 spec

* feat: inital new doc supporting oas2 and oas3 * docs: add new images * fix: support multiple schemas * docs: add configurations * docs: add index pages * docs: update README with OAS3
sanic-org · Apr 1, 2021 · 4a1b29b · 4a1b29b
1 parent 2c731ec
commit 4a1b29b
Show file tree

Hide file tree

Showing 42 changed files with 862 additions and 150 deletions.
diff --git a/README.md b/README.md
@@ -41,17 +41,17 @@ app.blueprint(swagger_blueprint)
 You'll now have a Swagger UI at the URL `/swagger/` and an OpenAPI 2.0 spec at `/swagger/swagger.json`.
 Your routes will be automatically categorized by their blueprints.
 
-## Example
+## OpenAPI 2
 
-Here is an example to use Sanic-OpenAPI:
+Here is an example to use Sanic-OpenAPI 2:
 
 ```python
 from sanic import Sanic
 from sanic.response import json
-from sanic_openapi import swagger_blueprint
+from sanic_openapi import openapi2_blueprint
 
 app = Sanic(name="AwesomeApi")
-app.blueprint(swagger_blueprint)
+app.blueprint(openapi2_blueprint)
 
 
 @app.route("/")
@@ -67,6 +67,34 @@ if __name__ == "__main__":
 And you can get your Swagger document at <http://localhost:8000/swagger> like this:
 ![](docs/_static/images/hello_world_example.png)
 
+## OpenAPI 3
+
+⚠️ Sanic OpenAPI 3 support is experimental. This feature may be subject to change in future releases.
+
+Here is an example to use Sanic-OpenAPI 3:
+
+```python
+from sanic import Sanic
+from sanic.response import json
+from sanic_openapi import openapi3_blueprint
+
+app = Sanic(name="AwesomeApi")
+app.blueprint(openapi3_blueprint)
+
+
+@app.route("/")
+async def test(request):
+    return json({"hello": "world"})
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=8000)
+
+```
+
+And you can get your Swagger document at <http://localhost:8000/swagger> like this:
+![](docs/_static/images3/hello_world_example.png)
+
 ## Documentation
 
 Please check the documentation on [Readthedocs](https://sanic-openapi.readthedocs.io)

diff --git a/docs/_static/images3/blueprint_class_based_view_example.png b/docs/_static/images3/blueprint_class_based_view_example.png
diff --git a/docs/_static/images3/blueprint_example.png b/docs/_static/images3/blueprint_example.png
diff --git a/docs/_static/images3/class_based_view_example.png b/docs/_static/images3/class_based_view_example.png
diff --git a/docs/_static/images3/composition_view_example.png b/docs/_static/images3/composition_view_example.png
diff --git a/docs/_static/images3/configurations/API_BASEPATH.png b/docs/_static/images3/configurations/API_BASEPATH.png
diff --git a/docs/_static/images3/configurations/API_CONTACT_EMAIL.png b/docs/_static/images3/configurations/API_CONTACT_EMAIL.png
diff --git a/docs/_static/images3/configurations/API_DESCRIPTION.png b/docs/_static/images3/configurations/API_DESCRIPTION.png
diff --git a/docs/_static/images3/configurations/API_HOST.png b/docs/_static/images3/configurations/API_HOST.png
diff --git a/docs/_static/images3/configurations/API_LICENSE_NAME.png b/docs/_static/images3/configurations/API_LICENSE_NAME.png
diff --git a/docs/_static/images3/configurations/API_LICENSE_URL.png b/docs/_static/images3/configurations/API_LICENSE_URL.png
diff --git a/docs/_static/images3/configurations/API_SCHEMES.png b/docs/_static/images3/configurations/API_SCHEMES.png
diff --git a/docs/_static/images3/configurations/API_TERMS_OF_SERVICE.png b/docs/_static/images3/configurations/API_TERMS_OF_SERVICE.png
diff --git a/docs/_static/images3/configurations/API_TITLE.png b/docs/_static/images3/configurations/API_TITLE.png
diff --git a/docs/_static/images3/configurations/API_VERSION.png b/docs/_static/images3/configurations/API_VERSION.png
diff --git a/docs/_static/images3/decorators/consumes_body.png b/docs/_static/images3/decorators/consumes_body.png
diff --git a/docs/_static/images3/decorators/consumes_header.png b/docs/_static/images3/decorators/consumes_header.png
diff --git a/docs/_static/images3/decorators/consumes_query.png b/docs/_static/images3/decorators/consumes_query.png
diff --git a/docs/_static/images3/decorators/description.png b/docs/_static/images3/decorators/description.png
diff --git a/docs/_static/images3/decorators/produces.png b/docs/_static/images3/decorators/produces.png
diff --git a/docs/_static/images3/decorators/sumary.png b/docs/_static/images3/decorators/sumary.png
diff --git a/docs/_static/images3/decorators/tag.png b/docs/_static/images3/decorators/tag.png
diff --git a/docs/_static/images3/hello_world_example.png b/docs/_static/images3/hello_world_example.png
diff --git a/docs/index.md b/docs/index.md
@@ -21,41 +21,10 @@ Or, use master banch from GitHub with latest features:
 pip install git+https://github.com/sanic-org/sanic-openapi.git
 ```
 
-## Getting Started
+## Getting started
 
-Here is an example to use Sanic-OpenAPI:
-
-```python
-from sanic import Sanic
-from sanic.response import json
-from sanic_openapi import swagger_blueprint
-
-app = Sanic()
-app.blueprint(swagger_blueprint)
-
-
-@app.route("/")
-async def test(request):
-    return json({"hello": "world"})
-
-
-if __name__ == "__main__":
-    app.run(host="0.0.0.0", port=8000)
-
-```
-
-And you can get your Swagger document at <http://localhost:8000/swagger> like this:
-![](_static/images/hello_world_example.png)
-
-## Contents
-
-* [Document Routes](sanic_openapi/document_routes)
-* [Configurations](sanic_openapi/configurations)
-* [Decorators](sanic_openapi/decorators)
-* [Fields](sanic_openapi/fields)
-* [API Factory](sanic_openapi/api_factory)
-* [Examples](sanic_openapi/examples)
-* [API Reference](sanic_openapi/api_reference)
+* [Sanic OpenAPI 2](/sanic_openapi2/index)
+* [Sanic OpenAPI 3 (Experimental)](/sanic_openapi3/index)
 
 ## Indices and tables
 

diff --git a/docs/sanic_openapi/api_reference.md → docs/sanic_openapi2/api_reference.md b/docs/sanic_openapi/api_reference.md → docs/sanic_openapi2/api_reference.md
@@ -3,16 +3,7 @@
 ## sanic_openapi.doc
 
 ```eval_rst
-.. automodule:: sanic_openapi.doc
-    :members:
-    :undoc-members:
-    :show-inheritance:
-```
-
-## sanic_openapi.swagger
-
-```eval_rst
-.. automodule:: sanic_openapi.swagger
+.. automodule:: sanic_openapi.openapi2.doc
     :members:
     :undoc-members:
     :show-inheritance:
@@ -21,7 +12,7 @@
 ## sanic_openapi.api
 
 ```eval_rst
-.. automodule:: sanic_openapi.api
+.. automodule:: sanic_openapi.openapi2.api
     :members:
     :undoc-members:
     :show-inheritance:

diff --git a/docs/sanic_openapi/configurations.md → docs/sanic_openapi2/configurations.md b/docs/sanic_openapi/configurations.md → docs/sanic_openapi2/configurations.md
@@ -21,10 +21,10 @@ By default, Swagger will use exactly the same host which served itself as the AP
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_HOST"] = "petstore.swagger.io"
 
     ```
@@ -41,10 +41,10 @@ By default, Swagger will use exactly the same host which served itself as the AP
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_BASEPATH"] = "/api"
 
     ```
@@ -61,10 +61,10 @@ By default, Swagger will use exactly the same host which served itself as the AP
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_SCHEMES"] = ["https"]
 
     ```
@@ -86,10 +86,10 @@ For more detail of those additional information, please check the [document](htt
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_VERSION"] = "0.1.0"
 
     ```
@@ -106,11 +106,11 @@ For more detail of those additional information, please check the [document](htt
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
-    app.config["API_TITLE"] = "Sanci-OpenAPI"
+    app.blueprint(openapi2_blueprint)
+    app.config["API_TITLE"] = "Sanic-OpenAPI"
 
     ```
 
@@ -126,10 +126,10 @@ For more detail of those additional information, please check the [document](htt
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_DESCRIPTION"] = "An example Swagger from Sanic-OpenAPI"
 
     ```
@@ -146,10 +146,10 @@ For more detail of those additional information, please check the [document](htt
 
   ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_TERMS_OF_SERVICE"] = "https://github.com/sanic-org/sanic-openapi/blob/master/README.md"
 
   ```
@@ -166,10 +166,10 @@ For more detail of those additional information, please check the [document](htt
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_CONTACT_EMAIL"] = "foo@bar.com"
 
     ```
@@ -186,10 +186,10 @@ For more detail of those additional information, please check the [document](htt
 
     python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_LICENSE_NAME"] = "MIT"
 
 
@@ -206,10 +206,10 @@ For more detail of those additional information, please check the [document](htt
 
     ```python
     from sanic import Sanic
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_LICENSE_URL"] = "https://github.com/sanic-org/sanic-openapi/blob/master/LICENSE"
 
     ```
@@ -229,10 +229,10 @@ If your API have to access with authentication, Swagger can provide related conf
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_SECURITY"] = [{"BasicAuth": []}]
     app.config["API_SECURITY_DEFINITIONS"] = {"BasicAuth": {"type": "basic"}}
 
@@ -257,10 +257,10 @@ If your API have to access with authentication, Swagger can provide related conf
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_SECURITY"] = [{"ApiKeyAuth": []}]
     app.config["API_SECURITY_DEFINITIONS"] = {
         "ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-KEY"}
@@ -284,10 +284,10 @@ If your API have to access with authentication, Swagger can provide related conf
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_SECURITY"] = [{"ApiKeyAuth": []}]
     app.config["API_SECURITY_DEFINITIONS"] = {
         "ApiKeyAuth": {"type": "apiKey", "in": "query", "name": "api_key"}
@@ -312,10 +312,10 @@ If your API have to access with authentication, Swagger can provide related conf
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_SECURITY"] = [{"OAuth2": []}]
     app.config["API_SECURITY_DEFINITIONS"] = {
         "OAuth2": {
@@ -347,10 +347,10 @@ By default, Sanic registers URIs both with and without a trailing `/`. You may s
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
 
 
     @app.get("/test")
@@ -370,10 +370,10 @@ By default, Sanic registers URIs both with and without a trailing `/`. You may s
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_URI_FILTER"] = "slash"
 
 
@@ -394,10 +394,10 @@ By default, Sanic registers URIs both with and without a trailing `/`. You may s
     from sanic import Sanic
     from sanic.response import json
 
-    from sanic_openapi import swagger_blueprint
+    from sanic_openapi import openapi2_blueprint
 
     app = Sanic()
-    app.blueprint(swagger_blueprint)
+    app.blueprint(openapi2_blueprint)
     app.config["API_URI_FILTER"] = "all"