Falcon 应用程序无法呈现 Openapi(swagger) 规范答案

【问题标题】：Falcon application can not render Openapi(swagger) specificationFalcon 应用程序无法呈现 Openapi(swagger) 规范
【发布时间】：2020-10-13 17:51:58
【问题描述】：

大家好，我们正在运行一个使用 falcon-apispec 库生成 OpenAPI 规范的 Falcon 应用程序。

这是我们初始化定义的代码：

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())

这是我们定义的 openapi-spec 定义：

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"

这是定义在帖子上应该做什么的类之一：

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())

每当我们尝试访问托管的 swagger-ui 时，都会遇到此错误：

无法呈现此定义提供的定义未指定有效的版本字段。请指明有效的 Swagger 或 OpenAPI 版本字段。支持的版本字段是 swagger: "2.0" 和那些匹配 openapi: 3.0.n 的（例如，openapi: 3.0.0）。

有谁知道我们如何解决这个问题？当我们将我们的 openapi 规范粘贴到位于此处的 swagger 编辑器时：https://editor.swagger.io/ 它工作得很好。任何帮助都会很棒！

【问题讨论】：

标签： python-3.x kubernetes swagger swagger-ui openapi

【解决方案1】：

调用APISpec 时，并非所有字符串都受支持。尝试类似“0.0.1”（您提供“最新”）。另外，使用 falcon_swagger_ui 时，如果 openapi_version 格式不正确，可能会报错（在这种情况下，提供了有效格式的示例）。

这对我有用：

规格 = APISpec( title="我的应用", 版本="0.0.1", openapi_version='3.0.0', 插件=[FalconPlugin(api)] )

【讨论】：