最近一直在写api文档,不知道兄弟们有没有和我一样的感受,写文档比写代码还难受,写代码逻辑实现提交就完事了,写api文档那才叫难受,有些不合理的地方给反复来回改好几遍,不止代码要改,文档要改,注释要改,关键是文档还要让别人能看得懂

为了解决这个痛点我想起了swagger ui文档,因为我在jumpserver api文档上看到过,像这样

能实现交互,在线调式的api文档正是我需要的

我们知道fastapi框架是原生支持swagger的,但是flask框架怎么搞呢

ai上提供了两个思路

这里是因为我原有的代码注释已经写的太多了,不想再因为文档侵入太多代码,所以我果断选择了第二种方式,当然如果有需要的兄弟可以根据自己的情况,第一种需要了解Flasgger,这个可以看官方文档学习

我们直接用浏览器打开Swagger Editor

swagger api文档在线编辑器,打开以后上面原有的会带有示例,将原有的示例清掉,写入我们自己开发系统的文档相关内容

左边侧可以编辑内容,右边是预览,如果编辑内容有语法报错的话,会有红色报错显示的,非常好用,至于说这种类似于yaml格式的api文档内容该如何编写,我的建议是你可以chat下

编辑完成后我们选择导出文件

这里我们直接导出为yaml文件

接下来我们用swagger ui来渲染该文件

ai步骤

上面步骤执行完成后我们需要用nginx作为web服务器来代理访问swagger ui下载下来的资源

添加nginx配置

location /api/docs {
   alias /home//docs/swagger-ui/dist;
   index index.html;

重载配置生效

最终的效果:

小结

工欲善其事必先利其器,好的易懂的api文档能帮助我们快速开发自己的内部系统或产品,这在前端后对接来说是非常重要,而且在编写文档的时候我们顺带重新review代码,减少了代码的不合理性和在调式过程中出现的一些bug