集成可选模块 swagger，提升 web 开发效率

[rexyan]

介绍

在 fishbase 应用场景中，web 应用程序占大部分，且多数为 flask 应用。现目前接口文档，调式方式等都需要单独编写。在 spring boot 中也早支持了 swagger，如果能将 swagger 在 fishbase 中进行集成。且是可选模块（可选择安装或者不安装），这样大大的为 web 开发者提供了更简便的调式方式，更能提高开发效率。

目的

1. 提升开发效率
2. 提升接口联调测试效率
3. 提升接口描述，文档建设能力

功能

1. 实时在线调试
2. 成为 fishbase 可选模块，默认不安装（用户不一定是 web 应用）
3. 以装饰器方式描述接口
4. 项目启动即启动（debug方式才启动）
5. 接口支持丰富多数参数，方法
6. 支持多级配置，优先级：自定义配置 -> 应用程序配置 -> 默认配置

预览

使用

class UserLogin(BaseHandler):
    @staticmethod
    @doc.summary("登录接口")
    @doc.description('用户登录')
    @doc.consumes({"verify_code": str}, required=True, location="body")
    @doc.consumes({"username": str}, required=True, location="body")
    @doc.consumes({"password": str}, required=True, location="body")
    @doc.consumes({'session_id': str}, location='header', required=True)
    def login():
        pass

效果

[itaa]

这个建议很好，可以添加进来，注意作为将相关依赖设置为非必须，采用 try import 的形式进行引用。

[rexyan]

使用技巧大致如下：

如何启用？

只需调用 flask_swagger，并传入 flask app 对象即可。

如何关闭？

只需将在 app 配置中将DEBUG设置为 False 即可关闭此功能。

如何添加接口摘要信息？

若想在文档中添加摘要信息，需在对应方法上添加 @doc.summary("xx业务查询接口", group="xx业务")() 装饰器。其中第一个参数为摘要描述信息，可选参数 group 可将接口进行分组

如何添加接口描述信息？

若想在文档中添加描述信息，需在对应方法上添加 @doc.description("测试 Swagger 使用, 实例采用蓝图的方式, 参数为 URL 参数 token, 且必传")() 装饰器。参数即为描述内容

参数为 url 参数时如何配置？

若参数为 url 参数， 需在对应方法上添加 @doc.consumes("token", required=True)() 装饰器，其中第一个参数为参数名称，可选参数 required 代表此参数是否必传，默认为 False。可选参数 location 代表此参数传递的位置，默认为 query。

参数为请求体参数时如何配置？

若参数为请求体参数，使用方法与参数为 url 参数类似，只需将第一个参数改为请求体参数对象(可以是一个类，或者字典)。location 设置为 body。例如： @doc.consumes(AddXxReqVo, location="body")()

如何进行接口在线调试？

使用 swagger，并且项目正常启动后，访问 http://ip:port/swagger 即可看到 flask app 所拥有的所有接口信息，点击 Try it out 即可进行在线调试。注意：为了安全起见，建议项目在生产环境运行时候关闭 swagger 功能，只需将 app 对象中的 DEBUG 设置为 False 即可。

使用效果如下：

[wingfish]

使用效果这里截图没有，这个特性完成了吧

[rexyan]

使用效果这里截图没有，这个特性完成了吧

有图。该特性已完成。