def enable_swagger(server_config: ServerConfig, app: web.Application):
"""
Enables Open API (a.k.a Swagger) on this server. This consists of:
* All endpoints within API specification are to be handled by a Open API handler that will validate requests
* If specified in server_config.api_docs_path, API docs site will be available at the given route.
i.e. http://server-address:8020/api/docs
:param server_config: server configuration
:param app: aiohttp web Application to host routes and docs
"""
global swagger, static_spec
if spec is None:
logger.warning(
__name__,
"No api-file loaded. OpenAPI docs and validation disabled.")
return
if diff_specs():
err = APIError(
"Cannot enable OpenAPI. Differences found between api-file and running apps. "
"Run `hopeit openapi diff` to check and `hopeit openapi update` to generate spec file"
)
logger.error(__name__, err)
raise err
static_spec = None
logger.info(__name__, "Enabling OpenAPI endpoints...")
app["AIOHTTP_SWAGGER3_SWAGGER_SPECIFICATION"] = spec
api_docs_ui = None
if server_config.api.docs_path:
api_docs_ui = RapiDocUiSettings(path=server_config.api.docs_path,
heading_text=spec['info']['title'],
theme='dark',
render_style='read',
layout='column',
schema_style='tree',
allow_spec_url_load=False,
allow_spec_file_load=False,
allow_server_selection=False,
show_header=False)
logger.info(
__name__,
f"OpenAPI documentation available in {server_config.api.docs_path}"
)
else:
logger.warning(
__name__,
"OpenAPI documentation path not specified in server config. API docs endpoint disabled."
)
swagger = Swagger(app,
validate=True,
spec=spec,
request_key="data",
rapidoc_ui_settings=api_docs_ui,
redoc_ui_settings=None,
swagger_ui_settings=None)
swagger.register_media_type_handler("multipart/form-data",
_passthru_handler)
logger.info(__name__, "OpenAPI validations enabled.")
def main():
app = web.Application()
s = SwaggerDocs(
app,
swagger_ui_settings=SwaggerUiSettings(path="/swagger"),
redoc_ui_settings=ReDocUiSettings(path="/redoc"),
rapidoc_ui_settings=RapiDocUiSettings(path="/rapidoc"),
)
s.add_routes([web.get("/", handler, allow_head=True)])
web.run_app(app)
def router(self):
"""Override this if you want to setup custom swaggerrouter."""
self.logger.info(f'Setting docs at {self.prefix}docs')
settings = RapiDocUiSettings(path=f'{self.prefix}docs',
theme="light",
show_header=False,
allow_server_selection=False)
description = ''
with suppress(Exception):
description = metadata.metadata(self.package_name)['Summary']
description = '\n'.join(
metadata.metadata(self.package_name).as_string().split(
'Description-Content-Type')[1].split('\n')[1:])
return SwaggerDocs(self.aiohttp_application,
title=self.package_name,
version=self.version['raw'],
description=description,
components=self.package_directory / 'openapi.yml',
swagger_ui_settings=settings,
request_key='payload')
def _rapidoc_ui_settings(**kwargs):
if "path" not in kwargs:
kwargs["path"] = "/docs"
return RapiDocUiSettings(**kwargs)