FlaskSwagger: 讓API文檔管理更簡單

一、 FlaskSwagger初探

FlaskSwagger是用於Flask應用程序的一個工具，可自動生成和展示API文檔，以便更輕鬆地管理API。

使用FlaskSwagger，我們不僅可以直觀地查看API的介面文檔，也可以在SwaggerUI提供的交互性界面中對API進行測試和調試。

from flask import Flask
from flask_restful import Api, Resource
from flask_swagger import swagger

app = Flask(__name__)
api = Api(app)

class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}

api.add_resource(HelloWorld, '/')

@app.route('/spec')
def spec():
    return swagger(app)

二、 部署FlaskSwagger

下面是部署FlaskSwagger的具體步驟：

1. 安裝FlaskSwagger

pip install flask-swagger

2. 在Flask應用中引用FlaskSwagger。

from flask_swagger import swagger

3. 設置Flask應用的文檔URL

@app.route('/spec')
def spec():
    return swagger(app)

4. 運行Flask應用

if __name__ == '__main__':
    app.run(debug=True)

三、 在SwaggerUI中展示API文檔

SwaggerUI是一種專門設計用於API文檔的互動式界面，可以更加清晰、明了的展示出API的各個欄位、參數，方便用戶與API進行互動式地體驗和調試。

通過FlaskSwagger，我們可以很容易地實現將SwaggerUI和API文檔整合在一起

只需在Flask代碼中添加以下路由即可：

from flask import Flask, request
from flask_restful import Resource, Api
from flask_swagger import swagger
from flask_swagger_ui import get_swaggerui_blueprint

app = Flask(__name__)
api = Api(app)

SWAGGER_URL = '/api/docs'  # URL for exposing Swagger UI (without trailing '/')
API_URL = '/spec'  # Our API url (can of course be a local resource)

# Call factory function to create our blueprint
swaggerui_blueprint = get_swaggerui_blueprint(
    SWAGGER_URL,
    API_URL,
    config={
        'app_name': "My Test Application"
    },
)

# Register blueprint at URL
# (URL must match the one given to factory function above)
app.register_blueprint(swaggerui_blueprint, url_prefix=SWAGGER_URL)

class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}

api.add_resource(HelloWorld, '/')

@app.route('/spec')
def spec():
    return swagger(app)

if __name__ == '__main__':
    app.run(debug=True)

四、 API文檔的自定義

在FlaskSwagger自動生成的API文檔中，我們可以通過下面兩種方式進行自定義：

1. 使用Python裝飾器自定義API信息

我們可以使用下述裝飾器來自定義API的信息：

from flask import Flask
from flask_restful import Resource, Api, fields, marshal_with
from flask_swagger import swagger

app = Flask(__name__)
api = Api(app)

resource_fields = {
    'name': fields.String,
    'address': fields.String,
    'date_updated': fields.DateTime,
}

class HelloWorld(Resource):

  @marshal_with(resource_fields)
  def get(self):
      """
      This endpoint will return a list of all the existing smells
      ---
      tags:
        - Smelly Things
      definitions:
        - schema:
            id: response
            properties:
              name:
                type: string
                default: "John"
              address:
                type: string
                default: "Street 1"
              date_updated:
                type: string
                format: date-time
                default: "2016-01-01T10:00:00Z"
        - schema:
            id: error_model
            properties:
              error:
                type: string
                description: description of error (should be short)
      responses:
        200:
          description: A list of all the smells
          schema:
            $ref: '#/definitions/response'
        500:
          description: An error occurred
          schema:
            $ref: '#/definitions/error_model'
      """
      return {'name': 'John', 'address': 'street 1', 'date_updated': '2016-01-01'}

api.add_resource(HelloWorld, '/')

@app.route('/spec')
def spec():
    swag = swagger(app)
    swag['info']['title'] = 'My API'
    swag['info']['description'] = 'Customize Swagger within Flask'
    return swag

2. 在SwaggerUI頁面中手動編輯API文檔

在SwaggerUI的界面中，我們可以編輯API文檔的信息，包括操作和參數等信息，可以方便快捷地對API進行調試和測試。

五、 總結

FlaskSwagger是一個非常實用的工具，能夠更加方便地管理API文檔，讓整個開發的過程更加輕鬆愉快。