def setup(app: web.Application,
*,
title: str,
version: str,
description: str,
openapi_version: str = "3.0.2",
path: str = "/api/spec.json",
validate: bool = False) -> None:
app["spec"] = APISpec(
title=title,
version=version,
openapi_version=openapi_version,
info={"description": description},
plugins=[MarshmallowPlugin()],
)
app.router.add_get(path, handler, name="api.spec")
for route in app.router.routes():
if hasattr(route.handler, "spec") and route.resource:
operation_spec = route.handler.spec["operation"] # type: ignore
app["spec"].path(
path=route.resource.canonical,
operations={route.method.lower(): operation_spec},
)
if validate:
validate_spec(app["spec"])
def test_openapi_tools_validate_v2():
ma_plugin = MarshmallowPlugin()
spec = APISpec(
title="Pets", version="0.1", plugins=(ma_plugin,), openapi_version="2.0"
)
openapi = ma_plugin.converter
spec.components.schema("Category", schema=CategorySchema)
spec.components.schema("Pet", {"discriminator": "name"}, schema=PetSchema)
spec.path(
view=None,
path="/category/{category_id}",
operations={
"get": {
"parameters": [
{"name": "q", "in": "query", "type": "string"},
{
"name": "category_id",
"in": "path",
"required": True,
"type": "string",
},
openapi.field2parameter(
field=fields.List(
fields.Str(),
validate=validate.OneOf(["freddie", "roger"]),
location="querystring",
),
default_in=None,
name="body",
),
]
+ openapi.schema2parameters(PageSchema, default_in="query"),
"responses": {200: {"schema": PetSchema, "description": "A pet"}},
},
"post": {
"parameters": (
[
{
"name": "category_id",
"in": "path",
"required": True,
"type": "string",
}
]
+ openapi.schema2parameters(CategorySchema, default_in="body")
),
"responses": {201: {"schema": PetSchema, "description": "A pet"}},
},
},
)
try:
utils.validate_spec(spec)
except exceptions.OpenAPIError as error:
pytest.fail(str(error))
def generate_schema(self) -> dict:
endpoints = self.declaration.endpoints
for url_prefix, endpoint_declaration in endpoints.items():
endpoint, name = endpoint_declaration
self.spec.add_path(
path='/' + url_prefix, # TODO: normalize url
operations=self._operations_from_endpoint(endpoint),
)
validate_spec(self.spec)
return self.spec.to_dict()
def run(self, filename):
try:
validate_spec(spec)
except OpenAPIError:
print(f'API spec is not valid')
exit(1)
with open(filename, 'w') as fp:
fp.write(spec.to_yaml())
print(f'API spec has been written into {filename}')
def test_swagger_tools_validate():
spec = APISpec(
title='Pets',
version='0.1',
plugins=['apispec.ext.marshmallow'],
)
spec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchema, extra_fields={'discriminator': 'name'})
spec.add_path(
view=None,
path='/category/{category_id}',
operations={
'get': {
'parameters': [
{'name': 'q', 'in': 'query', 'type': 'string'},
{'name': 'category_id', 'in': 'path', 'required': True, 'type': 'string'},
field2parameter(
field=fields.List(
fields.Str(),
validate=validate.OneOf(['freddie', 'roger']),
location='querystring',
),
name='body',
use_refs=False,
),
] + swagger.schema2parameters(PageSchema, default_in='query'),
'responses': {
200: {
'schema': PetSchema,
'description': 'A pet',
},
},
},
'post': {
'parameters': (
[{'name': 'category_id', 'in': 'path', 'required': True, 'type': 'string'}] +
swagger.schema2parameters(CategorySchema, spec=spec, default_in='body')
),
'responses': {
201: {
'schema': PetSchema,
'description': 'A pet',
},
},
}
},
)
try:
utils.validate_spec(spec)
except exceptions.SwaggerError as error:
pytest.fail(str(error))
def on_get(self, req, resp):
if validate_spec(self.spec):
resp.status = falcon.HTTP_200
resp.set_header("content-type", "application/json")
resp.media = self.spec.to_dict()
else:
log.error("OpenAPI spec did not pass validation")
resp.status = falcon.HTTP_500
def setup_openapi(
app: Application,
*,
title: str,
version: str,
description: str,
operations: List[Operation],
openapi_version: str = "3.0.2",
path: str = "/api/spec.json",
security: Optional[Tuple[str, Dict[str, str]]] = None,
) -> None:
app["spec"] = APISpec(
title=title,
version=version,
openapi_version=openapi_version,
info={"description": description},
plugins=[MarshmallowPlugin()],
)
if security:
app["spec"].components.security_scheme(*security)
app.router.add_get(path, openapi.handler, name="api.spec")
for method, path, view in operations:
app.router.add_route(method, path, view.handle)
operation = view.spec.generate()
operation.setdefault("description", view.__doc__)
app["spec"].path(
path=path,
operations={method.lower(): operation},
)
validate_spec(app["spec"])
def test_swagger_valid(self):
try:
utils.validate_spec(spec)
except exceptions.SwaggerError as error:
self.fail(str(error))
def test_openapi_tools_validate_v3():
ma_plugin = MarshmallowPlugin()
spec = APISpec(
title='Pets',
version='0.1',
plugins=(ma_plugin, ),
openapi_version='3.0.0',
)
#openapi = ma_plugin.openapi
spec.definition('Category', schema=CategorySchema)
spec.definition('Pet', schema=PetSchemaV3)
spec.add_path(
view=None,
path='/category/{category_id}',
operations={
'get': {
'parameters': [
{
'name': 'q',
'in': 'query',
'schema': {
'type': 'string'
},
},
{
'name': 'category_id',
'in': 'path',
'required': True,
'schema': {
'type': 'string'
},
},
], # + openapi.schema2parameters(PageSchema, default_in='query'),
'responses': {
200: {
'description': 'success',
'content': {
'application/json': {
'schema': PetSchemaV3,
},
},
},
},
},
'post': {
'parameters': ([
{
'name': 'category_id',
'in': 'path',
'required': True,
'schema': {
'type': 'string'
},
},
]),
'requestBody': {
'content': {
'application/json': {
'schema': CategorySchema,
},
},
},
'responses': {
201: {
'description': 'created',
'content': {
'application/json': {
'schema': PetSchemaV3,
},
},
},
},
},
},
)
try:
utils.validate_spec(spec)
except exceptions.OpenAPIError as error:
pytest.fail(str(error))
def test_spec_is_valid(self):
"""Test generated spec file is valid"""
spec = self.app.extensions['flask-rest-api']['ext_obj'].spec
assert validate_spec(spec)
def test_openapi_tools_validate_v2():
ma_plugin = MarshmallowPlugin()
spec = APISpec(
title='Pets',
version='0.1',
plugins=(ma_plugin, ),
openapi_version='2.0',
)
openapi = ma_plugin.openapi
spec.components.schema('Category', schema=CategorySchema)
spec.components.schema('Pet',
schema=PetSchema,
extra_fields={'discriminator': 'name'})
spec.path(
view=None,
path='/category/{category_id}',
operations={
'get': {
'parameters': [
{
'name': 'q',
'in': 'query',
'type': 'string'
},
{
'name': 'category_id',
'in': 'path',
'required': True,
'type': 'string'
},
openapi.field2parameter(
field=fields.List(
fields.Str(),
validate=validate.OneOf(['freddie', 'roger']),
location='querystring',
),
name='body',
use_refs=False,
),
] + openapi.schema2parameters(PageSchema, default_in='query'),
'responses': {
200: {
'schema': PetSchema,
'description': 'A pet',
},
},
},
'post': {
'parameters': ([{
'name': 'category_id',
'in': 'path',
'required': True,
'type': 'string'
}] + openapi.schema2parameters(CategorySchema,
default_in='body')),
'responses': {
201: {
'schema': PetSchema,
'description': 'A pet',
},
},
},
},
)
try:
utils.validate_spec(spec)
except exceptions.OpenAPIError as error:
pytest.fail(str(error))
def test_spec__should_be_valid():
assert validate_spec(spec)
