使用 Swagger 描述 API 的标头参数

Posted 2023-02-19

【中文标题】使用 Swagger 描述 API 的标头参数

【英文标题】：Header parameters describing an API with Swagger

【发布时间】：2020-11-21 07:15:14

【问题描述】：

我正在尝试使用 Swagger 来创建 Connexion API (Python+Flask) 的规范。很棒的工具。我知道 HTTP 请求标头** 不会作为常规参数传递给处理程序函数，但我需要能够从操作中获取请求标头。我读了https://connexion.readthedocs.io/en/latest/request.html#header-parameters。我使用 Swagger 编辑器 生成了一个最小的 python 服务器（概念证明），但它不能从头开始工作，这可能是需求方面的问题：

默认的 requirements.txt 不允许我启动服务器，显示此错误消息：

$ python3 -m swagger_server
Traceback (most recent call last):
  File "/usr/lib/python3.6/runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "/usr/lib/python3.6/runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "/home/agalindodev/tmp/python-flask-server/swagger_server/__main__.py", line 3, in <module>
    import connexion
  File "/home/agalindodev/tmp/python-flask-server/venv/lib/python3.6/site-packages/connexion/__init__.py", line 3, in <module>
    from .apis import AbstractAPI  # NOQA
  File "/home/agalindodev/tmp/python-flask-server/venv/lib/python3.6/site-packages/connexion/apis/__init__.py", line 1, in <module>
    from .abstract import AbstractAPI  # NOQA
  File "/home/agalindodev/tmp/python-flask-server/venv/lib/python3.6/site-packages/connexion/apis/abstract.py", line 14, in <module>
    from ..operation import Operation
  File "/home/agalindodev/tmp/python-flask-server/venv/lib/python3.6/site-packages/connexion/operation.py", line 7, in <module>
    from .decorators import validation
  File "/home/agalindodev/tmp/python-flask-server/venv/lib/python3.6/site-packages/connexion/decorators/validation.py", line 9, in <module>
    from werkzeug import FileStorage
ImportError: cannot import name 'FileStorage'

并修改 requirements.txt 从 connexion==1.1.15 移动到 connexion==2.6.0 它启动但我最终得到：

TypeError: my_job_create() missing 1 required positional argument: 'my_session'

这是我的环境：

1.操作系统和运行时：

Ubuntu 18.04 上的 python 3.6.9

2。 requirements.txt

# connexion == 1.1.15
connexion == 2.4.0
python_dateutil == 2.6.0
setuptools >= 21.0.0

3.完整的招摇规范：

swagger: "2.0"
basePath: /api
info:
  title: "Just a swagger test API"
  version: "1.0.0"
paths:
  /my_jobs:
    post:
      operationId: my_job.create
      tags:
        - MyJob
      summary: "Create a job"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
        - name: "my_session"
          in: "header"
          description: "Session id that's creating the job"
          required: True
          type: string
      responses:
        "201":
          description: "Successfully created a job"
          schema:
            $ref: "#/definitions/MyJob"
definitions:
  MyJob:
    type: "object"
    properties:
      id:
        type: "string"

4.错误： 使用修改后的 requirements.txt 我只是尝试发布一个创建，传递标头但它会生成一个错误：

$ curl -v -X POST --header 'Content-Type: application/json' --header 'Accept: application/problem+json' --header 'my_session:  "id": "xxxxx" ' 'http://0.0.0.0:8080/api/my_jobs'
*   Trying 0.0.0.0...
* TCP_NODELAY set
* Connected to 0.0.0.0 (127.0.0.1) port 8080 (#0)
> POST /api/my_jobs HTTP/1.1
> Host: 0.0.0.0:8080
> User-Agent: curl/7.58.0
> Content-Type: application/json
> Accept: application/problem+json
> my_session:  "id": "xxxxx" 
> 
* HTTP 1.0, assume close after body
< HTTP/1.0 500 INTERNAL SERVER ERROR
< Content-Type: application/problem+json
< Content-Length: 252
< Server: Werkzeug/0.12.2 Python/3.6.9
< Date: Sun, 02 Aug 2020 10:39:58 GMT
< 

  "detail": "The server encountered an internal error and was unable to complete your request.  Either the server is overloaded or there is an error in the application.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "about:blank"

* Closing connection 0

生成的 swagger 服务器转储此输出：

[2020-07-31 14:08:50,078] ERROR in app: Exception on /api/my_jobs [POST]
Traceback (most recent call last):
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/flask/app.py", line 2447, in wsgi_app
    response = self.full_dispatch_request()
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/flask/app.py", line 1952, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/flask/app.py", line 1821, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/flask/_compat.py", line 39, in reraise
    raise value
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/flask/app.py", line 1950, in full_dispatch_request
    rv = self.dispatch_request()
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/flask/app.py", line 1936, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/connexion/decorators/decorator.py", line 48, in wrapper
    response = function(request)
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/connexion/decorators/uri_parsing.py", line 173, in wrapper
    response = function(request)
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/connexion/decorators/validation.py", line 388, in wrapper
    return function(request)
  File "/.../python-flask-server/venv/lib/python3.6/site-packages/connexion/decorators/parameter.py", line 126, in wrapper
    return function(**kwargs)
TypeError: my_job_create() missing 1 required positional argument: 'my_session'
127.0.0.1 - - [31/Jul/2020 14:08:50] "POST /api/my_jobs HTTP/1.1" 500 -

我怎样才能让它工作？

非常感谢！！！

【问题讨论】：

这有帮助吗？ connexion.readthedocs.io/en/latest/… 和 github.com/zalando/connexion/issues/850

谢谢，海伦。我认为我的问题确实是关于 Swagger Editor 生成的 swagger 服务器的新手问题。 requirements.txt 对我不起作用。一旦移动到较新版本的 Connexion，它就会启动，但随后它无法管理标头。您最好发布一个工作 requirements.txt 。提前致谢！

【参考方案1】：

头参数不作为参数传递给处理函数 https://connexion.readthedocs.io/en/latest/request.html#header-parameters.

你不能用

  parameters:
  - name: "my_session"
    in: "header"
    description: "Session id that's creating the job"
    required: True
    type: string

你必须使用connexion.request.headers['my_session']

【讨论】：

感谢您的回复，Kevin，但它与我在问题中的解释相匹配，并且在我的环境中不起作用。我将把问题编辑得更简洁，给出库的版本和完整的招摇定义。请问，你能提供适合你的 requirements.txt 吗？ Swagger Editor 生成的 swagger 服务器对我不起作用，我不得不更改要求，可能是这个问题。提前致谢！