未使用oneOf的Swagger出现oneOf验证错误求助

问题 #

在Flask中搭建简单API时，使用的swagger.yaml未包含oneOf或ref，但启动时仍报与refs和oneOf相关的错误。

原swagger配置 #

swagger: "2.0"

info:
  title: Swagger Template
  description: A Template API
  version: "0.1"

paths:
  /analyse_coordonates:
    get:
      operationId: app.core.analyse_coords
      summary: Endpoint to receive coordonates and return bivouac zone
      parameters:
      - in: query
        name: e
        schema:
          type: string
        description: E coordonate
      - in: query
        name: n
        schema:
          type: string
        description: N coordonate
      produces:
      - text/plain
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: integer

报错信息 #

[2022-07-20 09:51:40 +0000] [8] [ERROR] Exception in worker process
Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/gunicorn/arbiter.py", line 589, in spawn_worker
    worker.init_process()
  File "/usr/local/lib/python3.8/site-packages/gunicorn/workers/base.py", line 134, in init_process
    self.load_wsgi()
  File "/usr/local/lib/python3.8/site-packages/gunicorn/workers/base.py", line 146, in load_wsgi
    self.wsgi = self.app.wsgi()
  File "/usr/local/lib/python3.8/site-packages/gunicorn/app/base.py", line 67, in wsgi
    self.callable = self.load()
  File "/usr/local/lib/python3.8/site-packages/gunicorn/app/wsgiapp.py", line 58, in load
    return self.load_wsgiapp()
  File "/usr/local/lib/python3.8/site-packages/gunicorn/app/wsgiapp.py", line 48, in load_wsgiapp
    return util.import_app(self.app_uri)
  File "/usr/local/lib/python3.8/site-packages/gunicorn/util.py", line 359, in import_app
    mod = importlib.import_module(module)
  File "/usr/local/lib/python3.8/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
  File "<frozen importlib._bootstrap>", line 991, in _find_and_load
  File "<frozen importlib._bootstrap>", line 975, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 671, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 843, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/back_end/run.py", line 6, in <module>
    APP = flask.create_app()
  File "/back_end/app/flask/__init__.py", line 15, in create_app
    app.add_api("swagger.yaml", strict_validation=True, validate_responses=True)
  File "/usr/local/lib/python3.8/site-packages/connexion/apps/flask_app.py", line 65, in add_api
    api = super().add_api(specification, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/connexion/apps/abstract.py", line 149, in add_api
    api = self.api_cls(specification,
  File "/usr/local/lib/python3.8/site-packages/connexion/apis/abstract.py", line 81, in __init__
    self.specification = Specification.load(specification, arguments=arguments)
  File "/usr/local/lib/python3.8/site-packages/connexion/spec.py", line 152, in load
    return cls.from_file(spec, arguments=arguments)
  File "/usr/local/lib/python3.8/site-packages/connexion/spec.py", line 106, in from_file
    return cls.from_dict(spec)
  File "/usr/local/lib/python3.8/site-packages/connexion/spec.py", line 143, in from_dict
    return Swagger2Specification(spec)
  File "/usr/local/lib/python3.8/site-packages/connexion/spec.py", line 37, in __init__
    self._validate_spec(raw_spec)
  File "/usr/local/lib/python3.8/site-packages/connexion/spec.py", line 215, in _validate_spec
    raise InvalidSpecification.create_from(e)
connexion.exceptions.InvalidSpecification: {'in': 'query', 'name': 'e', 'schema': {'type': 'string'}, 'description': 'E coordonate'} is not valid under any of the given schemas

Failed validating 'oneOf' in schema['properties']['paths']['patternProperties']['^/']['properties']['get']['properties']['parameters']['items']:
    {'oneOf': [{'$ref': '#/definitions/parameter'},
               {'$ref': '#/definitions/jsonReference'}]}

On instance['paths']['/analyse_coordonates']['get']['parameters'][0]:
    {'description': 'E coordonate',
     'in': 'query',
     'name': 'e',
     'schema': {'type': 'string'}}
[2022-07-20 09:51:40 +0000] [8] [INFO] Worker exiting (pid: 8)

解决方案 #

问题出在Swagger 2.0的参数格式规范上：对于query类型的参数，不能使用schema字段来定义类型，需要直接在参数节点下用type指定类型。

修改后的swagger.yaml配置如下：

swagger: "2.0"

info:
  title: Swagger Template
  description: A Template API
  version: "0.1"

paths:
  /analyse_coordonates:
    get:
      operationId: app.core.analyse_coords
      summary: Endpoint to receive coordonates and return bivouac zone
      parameters:
      - in: query
        name: e
        type: string
        description: E coordonate
      - in: query
        name: n
        type: string
        description: N coordonate
      produces:
      - text/plain
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: integer

说明 #

Swagger 2.0中，schema字段主要用于定义请求体（requestBody）或响应体的结构，而query、path等类型的参数需要直接声明type、format等属性。Connexion在严格校验模式下会严格遵循Swagger 2.0规范，因此原配置中的schema字段会触发校验错误。

内容的提问来源于stack exchange，提问作者Andy B.