Metadata-Version: 2.1
Name: sanic-openapi3e
Version: 0.5.8
Summary: OpenAPI v3 support for Sanic. Document and describe all parameters, including sanic path params. python 3.5+
Home-page: https://github.com/endafarrell/sanic-openapi
Author: Enda Farrell
Author-email: enda.farrell@gmail.com
License: MIT
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
Provides-Extra: testing
Requires-Dist: sanic (>=0.6.0)
Requires-Dist: loguru
Provides-Extra: testing
Requires-Dist: pytest; extra == 'testing'
Requires-Dist: pytest-cov; extra == 'testing'

# Sanic OpenAPI v3e

Give your Sanic API an OpenAPI v3 specification.

## Installation

```shell
pip install sanic-openapi3e
```

## Usage

### Import blueprint and use simple decorators to document routes:

```python
import sanic
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc

app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)

@app.get("/user/<user_id:int>")
@doc.summary("Fetches a user by ID")
@doc.response(200, "The user")
async def get_user(request, user_id):
    return sanic.response.json(locals())

app.go_fast()
```

You'll now have a specification at the URL `/openapi/spec.json`.
Your routes will be automatically categorized by their blueprints' 
names.


### Configure some of the things

```python
app.config.API_VERSION = '1.0.0'
app.config.API_TITLE = 'An API'
app.config.API_DESCRIPTION = 'An API description'
```

To have a `contact`, set at least one of (but preferably all) 
`app.config.API_CONTACT_NAME`, 
`app.config.API_CONTACT_URL` or
`app.config.API_CONTACT_EMAIL`. 

To have a `license`, `set app.config.API_LICENSE_NAME"` and 
optionally `app.config."API_LICENSE_URL"`.

To have a `termsOfService`, set
`app.config.API_TERMS_OF_SERVICE_URL`. 

Setting `components`, `security` and `externalDocs` requires you to 

* first create the relevant objects somewhere in your code (near to 
  where you create the `app`),
* set the appropriate `app.config.OPENAPI_COMPONENTS`, 
  `app.config.OPENAPI_SECURITY`,  
  `app.config.OPENAPI_EXTERNAL_DOCS`.

#### Use `app.config` to control spec generation


    hide_openapi_self = app.config.get("HIDE_OPENAPI_SELF", True)
    show_excluded = app.config.get("SHOW_OPENAPI_EXCLUDED", False)
    show_unused_tags = app.config.get("SHOW_OPENAPI_UNUSED_TAGS", False)

In practice, you don't usually want to document the `/swagger` nor 
`/openapi` routes, but by setting `app.config.HIDE_OPENAPI_SELF = False`
you can have them appear in the generated spec (and therefore swagger 
too). 

Your `@doc.exclude()` annotations are always respected, but if your 
config has `app.config.SHOW_OPENAPI_EXCLUDED = True` then a *second* 
spec at `/openapi/spec.all.json` is created. You generally won't want 
these to be on your production deployment, but you may want it for dev
and test purposes. 




### Describe route path parameters

```python
import sanic
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc
app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)

@app.get("/examples/test_id/<an_id:int>")
@doc.parameter(name="an_id", description="An ID", required=True, _in="path")
def test_id(request, an_id):
    return sanic.response.json(locals())
```

``sanic-openapiv3`` will recognise that the path parameter ``an_id`` is
described with ``@doc.parameter`` and will merge the details together.

You may wish to specify that a parameter be limited to a set of choices,
such as day-of-week or that it has a minimum value. These can be done 
for parameters in ``path``, ``query``, ``header`` and ``cookie``:

```python
import sanic
import sanic.request
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc

app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)

@app.get("/test/some_ids")
@doc.parameter(
    name="ids",
    description="Some IDs",
    required=True,
    choices=[1, 3, 5, 7, 11, 13],
    _in="query",
    schema=doc.Schema.Integers,
)
def test_some_ids(request: sanic.request.Request):
    query = request.query_string
    return sanic.response.json(locals())



@app.get("/examples/test_id_min/<an_id:int>")
@doc.parameter(
    name="an_id", description="An ID", required=True, _in="path", schema=int_min_4
)
def test_id_min(request, an_id: int):
    return sanic.response.json(locals())


int_min_4 = doc.Schema(
    _type="integer", _format="int32", minimum=4, description="Minimum: 4"
)  

```

### Deprecate route paths or parameters

A parameter can be marked as ``@deprecated()``:

```python
import sanic
import sanic.request
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc

app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)

@app.get("/examples/test_parameter__deprecated/<an_id:int>")
@doc.parameter(
    name="an_id", description="An ID", required=True, _in="path", deprecated=True
)
@doc.summary("A path deprecated parameter")
@doc.description("The parameter should be marked as deprecated")
def param__deprecated(request, an_id: int):
    return sanic.response.json(locals())
```

as can a whole route:

```python
import sanic
import sanic.request
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc

app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)

@app.get("/examples/test_path__deprecated/<an_id:int>")
@doc.parameter(
    name="an_id",
    description="An ID",
    required=True,
    _in="path",
)
@doc.summary("A path with parameter examples")
@doc.description("This is marked as being deprecated")
@doc.deprecated()
def path__deprecated(request, an_id: int):
    return sanic.response.json(locals())
```


### Exclude routes from appearing in the OpenAPI spec (and swagger)

Need to soft-launch an endpoint, or keep your swagger simple? 

```python
import sanic
import sanic.request
import sanic.response
from sanic_openapi3e import openapi_blueprint, swagger_blueprint, doc

app = sanic.Sanic(strict_slashes=True)
app.blueprint(openapi_blueprint)
app.blueprint(swagger_blueprint)

@app.get("/test/alpha_release")
@doc.exclude()
@doc.parameter(
    name="ids",
    description="Some IDs",
    required=True,
    choices=[1, 3, 5, 7, 11, 13],
    _in="query",
    schema=doc.Schema.Integers,
)
def test_some_ids(request: sanic.request.Request):
    query = request.query_string
    return sanic.response.json(locals())
```





