def test_schema_name_resolver_returns_none_v2(self, pet_schema):
def resolver(schema):
return None
spec = APISpec(
title="Test resolver returns None",
version="0.1",
openapi_version="2.0",
plugins=(MarshmallowPlugin(schema_name_resolver=resolver),),
)
spec.path(
path="/pet",
operations={"get": {"responses": {200: {"schema": pet_schema}}}},
)
get = get_paths(spec)["/pet"]["get"]
assert "properties" in get["responses"]["200"]["schema"]
def test_resolve_schema_dict_auto_reference_return_none(self, schema):
# this resolver return None
def resolver(schema):
return None
spec = APISpec(
title='Test auto-reference',
version='0.1',
openapi_version='2.0',
plugins=(
MarshmallowPlugin(schema_name_resolver=resolver,),
),
)
assert {} == get_definitions(spec)
with pytest.raises(APISpecError, match='Name resolver returned None for schema'):
spec.components.schema('analysis', schema=schema)
class Config:
SQLALCHEMY_DATABASE_URI = os.environ.get(
'DATABASE_URL') or 'sqlite:///' + os.path.join(base_dir, 'blog.db')
TEST_DATABASE_URI = 'sqlite:///' + os.path.join(base_dir, 'test.db')
SQLALCHEMY_TRACK_MODIFICATIONS = False
DEBUG = True
PORT = 5000
SECRET_KEY = 'supeR secret KeyS'
APISPEC_SPEC = APISpec(title='Notes Project',
version='v1',
plugins=[MarshmallowPlugin()],
securityDefinitions=security_definitions,
security=[],
openapi_version='2.0.0')
APISPEC_SWAGGER_URL = '/swagger' # URI API Doc JSON
APISPEC_SWAGGER_UI_URL = '/swagger-ui' # URI UI of API Doc
def __init__(self,
url="/api/docs/api-docs",
app=None,
request_data_name="data",
**kwargs):
plugin = MarshmallowPlugin()
self.spec = APISpec(openapi_version="3.0.2",
plugins=(plugin, ),
**kwargs)
self.url = url
self._registered = False
self._request_data_name = request_data_name
if app is not None:
self.register(app)
def spec_fixture(request):
ma_plugin = MarshmallowPlugin()
spec = APISpec(
title='Validation',
version='0.1',
plugins=(ma_plugin, ),
openapi_version=request.param,
)
return namedtuple(
'Spec',
('spec', 'marshmallow_plugin', 'openapi'),
)(
spec,
ma_plugin,
ma_plugin.openapi,
)
def test_resolve_schema_dict_auto_reference_return_none(self, schema):
def resolver(schema):
return None
spec = APISpec(
title="Test auto-reference",
version="0.1",
openapi_version="2.0",
plugins=(MarshmallowPlugin(schema_name_resolver=resolver),),
)
assert {} == get_schemas(spec)
with pytest.raises(
APISpecError, match="Name resolver returned None for schema"
):
spec.components.schema("analysis", schema=schema)
def test_schema_uses_ref_if_available_name_resolver_returns_none_v2(self):
def resolver(schema):
return None
spec = APISpec(
title="Test auto-reference",
version="0.1",
openapi_version="2.0",
plugins=(MarshmallowPlugin(schema_name_resolver=resolver),),
)
spec.components.schema("Pet", schema=PetSchema)
spec.path(
path="/pet", operations={"get": {"responses": {200: {"schema": PetSchema}}}}
)
get = get_paths(spec)["/pet"]["get"]
assert get["responses"]["200"]["schema"] == build_ref(spec, "schema", "Pet")
def __init__(
self,
api: falcon.API,
project_name: str,
api_hosts: Union[str, Sequence[str]] = "/",
api_version: str = "1.0.0",
description: str = "",
):
"""Resource for '/swagger.yaml'
:param api: Your falcon.API instance
:param project_name: Title for your documentation
:param api_hosts: List of places where api can be
:param api_version: String with number of version of you project
:param description: Absolute path to template with description of your project
"""
public_resources = set()
spec = APISpec(
title=project_name,
version=api_version,
openapi_version="3.0.2",
info={"description": description},
plugins=[MarshmallowPlugin()],
)
routes = collect_routes(api)
for resource in {type(route.resource) for route in routes}:
if resource.Meta.skip_doc:
continue
if resource.Meta.auth:
public_resources.add(resource)
spec.components.schema(resource.Meta.name, schema=resource)
models_definition = spec.to_dict()
docs = APIDocs(routes, models_definition, api_hosts,
frozenset(public_resources))
docs_data = docs.run()
pyaml.add_representer(
Decimal,
lambda dumper, data: dumper.represent_scalar(
"tag:yaml.org,2002:str", str(data)),
)
self.data = pyaml.dump(docs_data, safe=True)
def openapi_format(format="yaml", server="localhost", no_servers=False):
extra_specs = {
'info': {
'description':
'The Faraday REST API enables you to interact with '
'[our server](https://github.com/infobyte/faraday).\n'
'Use this API to interact or integrate with Faraday'
' server. This page documents the REST API, with HTTP'
' response codes and example requests and responses.'
},
'security': {
"ApiKeyAuth": []
}
}
if not no_servers:
extra_specs['servers'] = [{'url': f'https://{server}/_api'}]
spec = APISpec(
title="Faraday API",
version="2",
openapi_version="3.0.2",
plugins=[FaradayAPIPlugin(),
FlaskPlugin(),
MarshmallowPlugin()],
**extra_specs)
api_key_scheme = {
"type": "apiKey",
"in": "header",
"name": "Authorization"
}
spec.components.security_scheme("API_KEY", api_key_scheme)
response_401_unauthorized = {
"description":
"You are not authenticated or your API key is missing "
"or invalid"
}
spec.components.response("UnauthorizedError", response_401_unauthorized)
with app.test_request_context():
for endpoint in app.view_functions:
spec.path(view=app.view_functions[endpoint], app=app)
if format.lower() == "yaml":
print(spec.to_yaml())
else:
print(json.dumps(spec.to_dict(), indent=2))
def __init__(self, app):
self._app = app
self.route_descriptions = defaultdict(list)
super().__init__(exception_handlers=exception_handlers, debug=True)
self.spec = APISpec(
title="Sparrow API",
version="2.0",
openapi_version="3.0.0",
info={"description": "An API for accessing geochemical data"},
plugins=[MarshmallowPlugin()],
)
self.add_middleware(ServerTimings)
self._add_routes()
self._app.run_hook("api-initialized-v2", self)
def generate_swagger_file():
"""Automatically generates Swagger spec file based on RequestHandler
docstrings and saves it to the specified file_location.
"""
errors = []
file_location = os.path.join(os.path.dirname(__file__), '..', '..', 'docs',
'api_schema_v{}'.format(API_VERSION))
# Starting to generate Swagger spec file. All the relevant
# information can be found from here https://apispec.readthedocs.io/
security_settings = yaml.safe_load(OPENAPI_SPEC_SECURITY)
spec = APISpec(
title="Unmanic API",
version=str(API_VERSION),
openapi_version="3.0.0",
info=dict(description="Documentation for the Unmanic application API"),
plugins=[UnmanicSpecPlugin(), MarshmallowPlugin()],
servers=[
{
"url":
"http://localhost:8888/unmanic/api/v{}/".format(API_VERSION),
"description": "Local environment",
},
],
**security_settings)
# Looping through all the handlers and trying to register them.
# Handlers without docstring will raise errors. That's why we
# are catching them silently.
handlers = find_all_handlers()
for handler in handlers:
try:
spec.path(urlspec=handler)
except APISpecError as e:
errors.append("API Docs - Failed to append spec path - {}".format(
str(e)))
pass
# Write the Swagger file into specified location.
with open('{}.json'.format(file_location), "w", encoding="utf-8") as file:
json.dump(spec.to_dict(), file, ensure_ascii=False, indent=4)
# TODO: Remove YAML. It sucks!
with open('{}.yaml'.format(file_location), "w", encoding="utf-8") as file:
file.write(spec.to_yaml())
return errors
def openapi_format(format="yaml"):
spec = APISpec(
title="Faraday API",
version="2",
openapi_version="3.0.2",
plugins=[FaradayAPIPlugin(), MarshmallowPlugin()],
info={'description': 'The Faraday server API'},
)
with app.test_request_context():
for endpoint in app.view_functions:
spec.path(view=app.view_functions[endpoint], app=app)
if format.lower() == "yaml":
print(spec.to_yaml())
else:
print(json.dumps(spec.to_dict(), indent=2))
def parameters_json_schema(cls) -> Any:
"""
Return configuration parameters as OpenAPI.
"""
if not cls.parameters_schema:
return None
ma_plugin = MarshmallowPlugin()
spec = APISpec(
title="Database Parameters",
version="1.0.0",
openapi_version="3.0.0",
plugins=[ma_plugin],
)
spec.components.schema(cls.__name__, schema=cls.parameters_schema)
return spec.to_dict()["components"]["schemas"][cls.__name__]
def _apispec(self):
spec = APISpec(title=self.title,
version=self.version,
openapi_version=self.openapi_version,
plugins=[MarshmallowPlugin()],
**self._apispec_options)
for route in self.routes:
if self.routes[route].description:
operations = yaml_utils.load_operations_from_docstring(
self.routes[route].description)
spec.path(path=route, operations=operations)
for name, schema in self.schemas.items():
spec.components.schema(name, schema=schema)
return spec
def _register_openapi(app):
from ursh.schemas import TokenSchema, URLSchema
with app.app_context():
spec = APISpec(
openapi_version='3.0.2',
title='ursh - URL Shortener',
version='2.0',
plugins=(
FlaskPlugin(),
MarshmallowPlugin(),
),
)
spec.components.schema('Token', schema=TokenSchema)
spec.components.schema('URL', schema=URLSchema)
app.config['APISPEC_SPEC'] = spec
apispec = FlaskApiSpec(app)
apispec.register_existing_resources()
def create_app(test_config=None):
app = Flask(__name__, instance_relative_config=True)
app.config.from_object(configs[env])
app.config.update({
'APISPEC_SPEC': APISpec(
title='openforms',
version='v1',
openapi_version='2.0',
plugins=[MarshmallowPlugin()],
),
'APISPEC_SWAGGER_URL': '/swagger/',
'APISPEC_SWAGGER_UI_URL': '/docs/',
})
register_extensions(app)
global celery
celery = make_celery(app)
return app
def _init_spec():
return APISpecBuilder(
title="{{cookiecutter.project_name}}",
version=VERSION,
openapi_version=OPENAPI_VERSION,
info=dict(description="{{cookiecutter.project_description}}"),
components={
'securitySchemes': {
'auth_tkt': {
'type': 'apiKey',
'name': 'auth_tkt',
'in': 'cookie'
}
}
},
plugins=(MarshmallowPlugin(),)
)
def docs_config(app):
app.config.update({
'APISPEC_SPEC':
APISpec(title='API Tren',
version='v1',
plugins=[MarshmallowPlugin()],
openapi_version='2.0.0'),
'APISPEC_SWAGGER_URL':
'/swagger/', # URI to access API Doc JSON
'APISPEC_SWAGGER_UI_URL':
'/docs/' # URI to access UI of API Doc
})
docs = FlaskApiSpec(app)
return docs
def _init_spec(
self,
flask_plugin=None,
marshmallow_plugin=None,
extra_plugins=None,
openapi_version=None,
**options,
):
# Plugins
self.flask_plugin = flask_plugin or FlaskPlugin()
self.ma_plugin = marshmallow_plugin or MarshmallowPlugin()
plugins = [self.flask_plugin, self.ma_plugin]
plugins.extend(extra_plugins or ())
# APISpec options
openapi_version = self._app.config.get('OPENAPI_VERSION',
openapi_version)
if openapi_version is None:
raise OpenAPIVersionNotSpecified(
'The OpenAPI version must be specified, either as '
'"OPENAPI_VERSION" app parameter or as '
'"openapi_version" spec kwarg.')
openapi_major_version = int(openapi_version.split('.')[0])
if openapi_major_version < 3:
base_path = self._app.config.get('APPLICATION_ROOT')
options.setdefault('basePath', base_path)
options.setdefault('produces', ['application/json'])
options.setdefault('consumes', ['application/json'])
options.update(self._app.config.get('API_SPEC_OPTIONS', {}))
# Instantiate spec
self.spec = apispec.APISpec(
self.title,
self._app.config.get('API_VERSION', '1'),
openapi_version=openapi_version,
plugins=plugins,
**options,
)
# Register custom fields in spec
for args in self._fields:
self._register_field(*args)
# Register custom converters in spec
for args in self._converters:
self._register_converter(*args)
def check_web_framework_and_marshmallow_plugin(web_framework_plugin, **kwargs_for_add_path):
"""Check schemas passed in web framework view function docstring are parsed by MarshmallowPlugin"""
spec = APISpec(
title='Swagger Petstore',
version='1.0.0',
plugins=[web_framework_plugin(), MarshmallowPlugin()],
openapi_version='2.0',
)
spec.add_path(**kwargs_for_add_path)
expected = {
'type': 'object',
'properties': {
'id': {'type': 'integer', 'format': 'int32', 'description': 'Pet id', 'readOnly': True},
'name': {'type': 'string', 'description': 'Pet name'},
},
'required': ['name'],
}
assert spec.to_dict()['paths']['/hello']['get']['responses'][200]['schema'] == expected
def init_app(self, **kwargs):
"""
Override base init_app method.
:param kwargs: args
"""
self.spec = APISpec(title=self.title,
version=self.version,
info={'description': self.top_level_description},
plugins=[MarshmallowPlugin()],
openapi_version='2.0')
self.resource_converter = ResourceConverter(self.app, self.spec)
self.view_converter = ViewConverter(self.app, self.spec)
self.add_swagger_routes()
for deferred in self._deferred:
deferred()
def swag_init(app):
# Create an APISpec
spec = APISpec(title='Messaging App',
version='1.0',
openapi_version='2.0',
plugins=[FlaskPlugin(), MarshmallowPlugin()])
template = spec.to_flasgger(
app,
definitions=[MessageSchema],
)
# set the UIVERSION to 3
app.config['SWAGGER'] = {'uiversion': 3}
# start Flasgger using a template from apispec
swag = Swagger(app, template=template)
return swag
def __init__(self, app=None, spec_kwargs=None, decorators=None, tags: Dict[str, str] = None):
"""
:param spec_kwargs:
:param decorators:
:param tags: {'<name tag>': '<description tag>'}
"""
self.decorators_for_autodoc = decorators or tuple()
self.spec_kwargs = spec_kwargs if spec_kwargs is not None else {}
self.spec = None
self.spec_tag = {}
self.spec_schemas = {}
self.app = None
self._fields = []
# Use lists to enforce order
self._fields = []
self._converters = []
# Инициализация ApiSpec
self.app = app
self._app = app
# Initialize spec
openapi_version = app.config.get("OPENAPI_VERSION", "2.0")
openapi_major_version = int(openapi_version.split(".")[0])
if openapi_major_version < 3:
base_path = app.config.get("APPLICATION_ROOT")
# Don't pass basePath if '/' to avoid a bug in apispec
# https://github.com/marshmallow-code/apispec/issues/78#issuecomment-431854606
# TODO: Remove this condition when the bug is fixed
if base_path != "/":
self.spec_kwargs.setdefault("basePath", base_path)
self.spec_kwargs.update(app.config.get("API_SPEC_OPTIONS", {}))
self.spec = APISpec(
app.name,
app.config.get("API_VERSION", "1"),
openapi_version=openapi_version,
plugins=[MarshmallowPlugin(), RestfulPlugin()],
**self.spec_kwargs,
)
tags = tags if tags else {}
for tag_name, tag_description in tags.items():
self.spec_tag[tag_name] = {"name": tag_name, "description": tag_description, "add_in_spec": False}
self._add_tags_in_spec(self.spec_tag[tag_name])
def __init__(
self,
app,
title,
version,
plugins=None,
description=None,
terms_of_service=None,
contact=None,
license=None,
openapi=None,
openapi_route="/schema.yml",
docs_route="/docs/",
static_route="/static",
):
self.app = app
self.schemas = {}
self.title = title
self.version = version
self.description = description
self.terms_of_service = terms_of_service
self.contact = contact
self.license = license
self.openapi_version = openapi
self.openapi_route = openapi_route
self.docs_theme = DEFAULT_API_THEME
self.docs_route = docs_route
self.plugins = [MarshmallowPlugin()] if plugins is None else plugins
if self.openapi_version is not None:
self.app.add_route(self.openapi_route, self.schema_response)
if self.docs_route is not None:
self.app.add_route(self.docs_route, self.docs_response)
theme_path = (Path(apistar.__file__).parent / "themes" /
self.docs_theme / "static").resolve()
self.static_route = static_route
self.app.static_app.add_directory(theme_path)
def build_routes(app):
"""Register routes to given app instance."""
app.config.update({
'APISPEC_SPEC':
APISpec(
title=SERVICE_NAME,
openapi_version=OPENAPI_VERSION,
version=API_VERSION,
plugins=[MarshmallowPlugin()],
),
'APISPEC_SWAGGER_URL': API_SPEC_URL,
})
app.register_blueprint(cache_blueprint)
app.register_blueprint(dataset_blueprint)
app.register_blueprint(jobs_blueprint)
app.register_blueprint(templates_blueprint)
swaggerui_blueprint = get_swaggerui_blueprint(
SWAGGER_URL, API_SPEC_URL, config={'app_name': 'Renku Service'}
)
app.register_blueprint(swaggerui_blueprint, url_prefix=SWAGGER_URL)
docs = FlaskApiSpec(app)
docs.register(list_uploaded_files_view, blueprint=CACHE_BLUEPRINT_TAG)
docs.register(upload_file_view, blueprint=CACHE_BLUEPRINT_TAG)
docs.register(project_clone_view, blueprint=CACHE_BLUEPRINT_TAG)
docs.register(list_projects_view, blueprint=CACHE_BLUEPRINT_TAG)
docs.register(migrate_project_view, blueprint=CACHE_BLUEPRINT_TAG)
docs.register(migration_check_project_view, blueprint=CACHE_BLUEPRINT_TAG)
docs.register(list_datasets_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(list_dataset_files_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(add_file_to_dataset_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(create_dataset_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(import_dataset_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(edit_dataset_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(unlink_file_view, blueprint=DATASET_BLUEPRINT_TAG)
docs.register(list_jobs, blueprint=JOBS_BLUEPRINT_TAG)
docs.register(
read_manifest_from_template, blueprint=TEMPLATES_BLUEPRINT_TAG
)
def init_app(self, app):
"""Initialize the Redoc.
:param app: Flask app
"""
self.app = app
self.config.update(self.app.config.get('REDOC', {}))
if len(self.config['marshmallow_schemas']) > 0:
self.config['plugins'].append(MarshmallowPlugin())
if self.spec_file is not None:
self.spec_file = self.load_spec_file(self.spec_file)
self.config['title'] = self.spec_file['info']['title']
self.config['version'] = self.spec_file['info']['version']
self.config['openapi_version'] = self.spec_file['openapi']
self.config['info'] = self.spec_file['info']
self.spec = APISpec(title=self.config['title'],
version=self.config['version'],
openapi_version=self.config['openapi_version'],
info=self.config['info'],
plugins=self.config['plugins'])
self.app.before_first_request(self.docstrings_to_openapi)
bp = Blueprint(self.config.get('endpoint', 'redoc'),
__name__,
url_prefix=self.config.get('url_prefix', None),
template_folder=self.config.get('template_folder',
'templates'),
static_folder=self.config.get('static_folder',
'static'),
static_url_path=self.config.get('static_url_path'))
bp.add_url_rule(self.config.get('spec_route'),
'docs',
view_func=self.docs_view)
bp.add_url_rule(self.config.get('spec_route') + '/json',
'docs_json',
view_func=self.docs_json)
self.app.register_blueprint(bp)
class BaseConfig:
TODOISM_ITEM_PER_PAGE = 20
TODOISM_LOCALES = ['en_US', 'zh_Hans_CN']
# SERVER_NAME = 'miali.dev:5000'
SECRET_KEY = os.getenv('SECRET_KEY', 'secret string')
SQLALCHEMY_DATABASE_URI = prefix + os.path.join(basedir, 'data.db')
SQLALCHEMY_TRACK_MODIFICATIONS = False
BABEL_DEFAULT_LOCALE = TODOISM_LOCALES[1]
APISPEC_SPEC = APISpec(
title='pets',
version='1.0.0',
openapi_version='3.0.2',
plugins=[MarshmallowPlugin()],
)
APISPEC_SWAGGER_URL = '/swagger/'
def __init__(self, title: str, version: str, description: str, openapi_version="3.0.0"):
assert apispec is not None, "`apispec` must be installed to use SchemaGenerator."
from apispec.ext.marshmallow import MarshmallowPlugin
marshmallow_plugin = MarshmallowPlugin()
self.spec = apispec.APISpec(
title=title,
version=version,
openapi_version=openapi_version,
info={"description": description},
plugins=[marshmallow_plugin],
)
self.converter = marshmallow_plugin.converter
self.resolver = marshmallow_plugin.resolver
# Builtin definitions
self.schemas = SchemaRegistry(self.spec, self.resolver)
def __init__(self, title, version, openapi_version, plugins=(), **options):
self.flask_plugin = FlaskPlugin()
self.ma_plugin = MarshmallowPlugin()
plugins = [self.flask_plugin, self.ma_plugin] + list(plugins)
openapi_major_version = int(openapi_version.split('.')[0])
if openapi_major_version < 3:
options.setdefault('produces', [
'application/json',
])
options.setdefault('consumes', [
'application/json',
])
super().__init__(
title=title,
version=version,
openapi_version=openapi_version,
plugins=plugins,
**options,
)
def _init_api(self):
# Create an APISpec
self.apispec = APISpec(
title='Shepherd',
version=__version__,
openapi_version='3.0.0',
plugins=[
FlaskPlugin(),
MarshmallowPlugin(),
],
)
self.apispec.components.schema('FlockId', schema=FlockIdSchema)
self.apispec.components.schema('FlockRequestOpts', schema=FlockRequestOptsSchema)
self.apispec.components.schema('GenericResponse', schema=GenericResponseSchema)
self.apispec.components.schema('LaunchResponse', schema=LaunchResponseSchema)
