feat: add types to openapi

[astagi]

I removed tests/test_api_oas3.py because it uses api module, which depends by doc module

This PR allows to:

• expose openapi
• use types from openapi

You can document your OAS3 API in this way

from sanic import Sanic
from sanic.response import json as json_response
from sanic_openapi import openapi, oas3_blueprint

app = Sanic("AwesomeApi")
app.blueprint(oas3_blueprint)

class Car:
    manufacturer = openapi.String(description="Car manufacturer", required=True)
    model = openapi.String(description="Car model", required=True)
    production_date = openapi.Date(description="Car year", required=True)

class Garage:
    spaces = openapi.Integer(description="Space available in the garage", required=True)
    cars = openapi.Array(Car, required=True)

@app.post('/garage')
@openapi.description("Create a new garage")
@openapi.body(
    { "application/json" : Garage },
    description="Body description",
    location="/garage",
    required=True,
)
@openapi.response(
    201, { "application/json" : Garage }, "A new Garage is created"
)
async def create_garage(request):
    return json_response(request.json, 201)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000, debug=True)

[astagi]

@ahopkins @artcg

I'll add more tests later.

[artcg]

Nice to see a usage example like that, we should get that code snippet in /examples maybe! Looks good, will leave a comment

[astagi]

@artcg I've just added an example for OAS3. Everything works fine, except header parameters. I added AUTHORIZATION header parameter in car_put

@openapi.parameter("AUTHORIZATION", str, location="header")
@openapi.response(200, {"application/json" : Car})
def car_put(request, car_id):
    return json(test_car)

Swagger interface detects the header parameter correctly but when I try out the API call it's not included in the curl command. Any ideas?

[artcg]

Looks great, taking a look at that header issue now

[artcg]

Ah in openapi3:

header parameters for "authorization" are ignored as it recommends to use securityschema instead, so can replace that header with something else for the example maybe...

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject

[astagi]

hey @artcg thanks for having looked at this! I'll replace it with SecurityScheme then and see if it works as expected!

[astagi]

@artcg I updated SecurityScheme to make it working in cars example. I don't know if it's my fault, but itooks like Swagger interface is not working as expected, in put car method when @openapi.secured decorator is applied I see a little padlock

every time I try to call the API, no value is included in the header by curl again.

Specs also suggest to define securitySchemes object into components, but ComponentsBuilder is commented inside builders.py. Thoughts? (an example here)

[artcg]

Ah looks like we will need the Components field supported for this which will be a bit of a chore, will push something later in the week, until then, lets merge what looks good so far, can you open a new PR from a new branch based upon this one for the security changes?

[astagi]

eheh totally agree @artcg! I'm going to start working on oas3 naming changes and folders structure.. Thank you for your support!