使用 Swagger 在同一 def 中使用 HTTP 方法的语法

Question

我是 Swagger 的新手UI。在我的 python 代码中，我有一个名为 'work' 的 API，它支持 POST、PUT 和 DELETE HTTP 方法。

现在我想为它创建 Swagger 文档。我正在使用以下代码：

@app.route('/work', methods=['POST', 'PUT', 'DELETE'])
def work():
"""
    Micro Service Based API for work operations
    This API is for work to task matching operations
    ---
    paths:
      /cv:
        put:
          parameters:
            - name: body
              in: body
              required: true
              schema:
                id: data
                properties:
                    _id:
                        type: string
              description: Id
          responses:
                    200:
                        description: Please wait the calculation, you'll receive an email with results
        delete:
          parameters:
            - name: body
              in: body
              required: true
              schema:
                id: data
                properties:
                    _id:
                        type: string
              description: Id
          responses:
                    200:
                        description: Please wait the calculation, you'll receive an email with results
        post:
          responses:
                    200:
                        description: done
"""

不过好像不行。

我尝试浏览以下文档 link 但没有多大帮助 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathsObject

你能帮帮我吗？

每个 HTTP 方法请求的参数都是不同的，我也希望在我的 HTTP 中为每个方法指定不同的描述 UI。

编辑

将此添加到 index.yml 文件。

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  schemes:
- "http"
paths:
  /work:
    put:
      tags:
  - "WORK"
  summary: "Update a Work Score"
  description: ""
  consumes:
  - "application/json"
  parameters:
  - in: "body"
    name: "body"
    description: "Work ID whose score needs to be updates"
    required: true
    schema:
      $ref: "#/definitions/Data"
  responses:
    200:
      description: "Invalid input"
  /scoreCompute:
    post:
  tags:
  - "ABCD"
  summary: "Compute ABCD"
  description: ""
  consumes:
  - "application/json"
  parameters:
  - in: "body"
    name: "body"
    description: "Compute ABCD"
    required: true
    schema:
      $ref: "#/definitions/TaskId"
  responses:
    200:
      description: "Invalid input"
definitions:
  Data:
type: object
properties:
  _id:
    type: string
    description: Enter ID
  TaskId:
type: object
properties:
  job_id:
    type: string
    description: Enter ID

对 python 代码进行了上述更改。

@app.route('/work', methods=['POST', 'PUT', 'DELETE'])
@swag_from('index.yml')
def work():

然而 http://127.0.0.1:5000/apidocs/#!/default/ 什么也没显示。

Answer 1

如果您正在使用 Flasgger (http://github.com/rochacbruno/flasgger) 遗憾的是，它还不支持在同一个文档字符串中定义不同的 HTTP 方法，有这个 issue opened.

但是，有一种解决方法可以使其正常工作。

1) 将您的 YAML 放在一个单独的文件中
2) 从 Swagger template_file

加载它

YAML 文件，另存为 test.yaml:

definitions:
  Data:
    type: object
    properties:
      _id:
        type: string

paths:
  /cv:
    put:
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Data'
      responses:
        200:
          description: |
            Please wait the calculation, you'll receive an email with results
    delete:
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Data'
      responses:
        200:
          description: |
            Please wait the calculation, you'll receive an email with results
    post:
      responses:
        200:
          description: done

然后 test.py

from flask import Flask
from flasgger import Swagger


app = Flask(__name__)
Swagger(app, template_file='test.yaml')


@app.route('/cv', methods=['POST', 'PUT', 'DELETE'])
def cv():
    """
    Micro Service Based API for CV operations
    This API is for job to CVs matching operations
    """


app.run(debug=True)

你得到

使用 Swagger 在同一 def 中使用 HTTP 方法的语法

Syntax for HTTP methods in same def using Swagger

python

flask

swagger

swagger-ui

flasgger