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

Question

我是SwaggerUI的新手。在我的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 
""" 

但是，它似乎没有工作。

我试图浏览下面的文档链接，但不要太大的帮助 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）从扬鞭加载它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) 

而你得到