Falcon application can not render Openapi(swagger) specification - python-3.x

Question

Hello everyone we are running a Falcon application that uses the falcon-apispec library to generate OpenAPI specifications.
Here is our code that initializes the definition:
import falcon
from apispec import APISpec
from falcon_apispec import FalconPlugin
from kubernetes import config
from api.admission_response import AdmissionResponse
from api.health import Health
from api.k8s_config_validator import K8sConfigValidator
from api.middleware.json import RequireJSON, JSONTranslator
from api.apidocs import ApiDocs
def create_app(config_validator):
api = falcon.API(middleware=[
RequireJSON(),
JSONTranslator(),
])
resources ={
'/': AdmissionResponse(config_validator),
'/api-docs': ApiDocs(),
'/health': Health()
}
for r in resources:
api.add_route(r, resources[r])
setup_swagger_documentation(api, resources)
# initialize k8s client
config.load_incluster_config()
return api
def get_app():
return create_app(K8sConfigValidator())
def setup_swagger_documentation(api, resources):
spec = APISpec(
title='Admission Controller API',
version='latest',
openapi_version='2.0',
plugins=[
FalconPlugin(api)
],
info=dict(description="Admission Controller API"),
)
for r in resources:
spec.path(resource=resources[r])
with open('./api/config/openapi/openapi_spec.yaml', 'w') as f:
f.write(spec.to_yaml())
Here is our openapi-spec defintion defined:
openapi: 3.0.0
info:
description: Admission Controller API
title: Admission Controller API
version: latest
paths:
/:
post:
tags:
- "API"
parameters:
- in: "query"
name: "body"
description: "List of user object"
required: true
schema:
type: string
responses:
"200":
description: "Success"
/api-docs:
get:
tags:
- "API Doc Endpoints"
responses:
"200":
description: "Success"
/health:
get:
tags:
- "Health Endpoints"
responses:
"200":
description: "Success"
And here is one of the classes that defines what should be done on a post:
class AdmissionResponse(object):
def __init__(self, k8s_config_validator):
self.k8s_config_validator = k8s_config_validator
#falcon.before(validate_schema)
def on_post(self, req, resp):
"""
---
tags: ['API']
parameters:
- in: "query"
name: "body"
description: "List of user object"
required: true
type: string
responses:
"200":
description: "Success"
"""
admission_review = AdmissionReview(req.context['doc'])
errors = self.k8s_config_validator.validate(admission_review)
if errors:
resp.context['result'] = ResponseBuilder(admission_review).not_allowed(errors)
api.logger.info("Validations for %s of kind %s in %s failed with %s", admission_review.name(), admission_review.kind(), admission_review.namespace(), errors)
else:
resp.context['result'] = ResponseBuilder(admission_review).allowed()
api.logger.info("Validations for %s of kind %s in %s passed", admission_review.name(), admission_review.kind(), admission_review.namespace())
Whenever we try to hit our hosted swagger-ui we run into this error:
Unable to render this definition The provided definition does not specify a valid version field.
Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).
Does anyone know how we could resolve this? When we paste in our openapi specification to the swagger editor located here: https://editor.swagger.io/ it works just fine. Any help would be awesome!

Answer 1

When calling APISpec, not all strings are supported.
Try something like "0.0.1" (you supplied 'latest').
Also, using falcon_swagger_ui, an error may be reported if the openapi_version format is not correct (in such case, examples of valid formats are provided).
This works for me:
spec = APISpec(
title="My APP",
version="0.0.1",
openapi_version='3.0.0',
plugins=[FalconPlugin(api)]
)