Metadata-Version: 2.1
Name: sanic-openapi3e
Version: 0.5.1
Summary: OpenAPI v3 support for Sanic
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'
```

Other items, like servers, contact, termsOfService are still a
 work-in-progress.


### 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
@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
@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
@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=oas_types.Schema.Integers,
)
def test_some_ids(request: sanic.request.Request):
    query = request.query_string
    return sanic.response.json(locals())
```





