【Go】Swagger v2 转 OpenApi v3 CLI - swag2op

写这个工具的原因,也是受万俊峰老师的启发,他把工作中重复的事情,整合到一个工具,然后开源,这件事很赞。

swag2op

【Go】Go Swagger 生成和转 openapi 3.0.3 这篇文档,主要是对 swagger 如何生成,以及如何用代码把生成的 swagger.json 转为 OpenApi 的 spec。总觉着这样很不直觉,而且都得再指定,再去转,有些麻烦。原本 swagger2openapi3 的 roadmap 也就是要写一个 cli,那刚好这篇就说明一下这个 cli 的用法。

swagger2openapi3 下的 cmd/swag2op 就是通过指令直接生成 OpenApi v3.0.3 的 cli。

swag2op 完全继承 swag 的用法,设计的时候就是想不要改变原本生成 swag 的方法,可以使用原来的,也可以在此基础上能够生成 OpenApi v3 的 spec。

安装方式也很简单:

bash 复制代码
go install github.com/zxmfke/swagger2openapi3/cmd/swag2op@latest

使用方式遵循 swag 的用法:

bash 复制代码
swag2op init
新增 flag

swag2op 提供了三个额外的 flag,以提供更多的灵活性:

  1. disableConvertOpenApiV3Flag

    这个标志决定是否将生成的 swagger.json 转换为 OpenAPI v3 格式。默认情况下是启用的。设计的时候也在想,有些人可能就是有时候要 OpenApi v3,有时候又不需要,所以提供这个 flag 可以更灵活。

  2. disableOverwriteSwaggerV2Flag

    这个标志决定是否在生成 OpenAPI v3.0 json 时不覆盖原始的 swagger.json。默认情况下是禁用的。swag2op 设计的时候就是直接生成 OpenApi 的 spec,又要保持原来在 docs 的目录下面,所以就得去覆盖原来的 docs 下的 swagger.json 和 swagger.yaml。不过有些人可能考虑我既要保留原本的,也要生成 OpenApi 的,所以就提供这个 flag。

  3. openapiOutputDirFlag

    这个标志指定生成的OpenAPI v3规范的输出目录。默认值是./openapi。

测试

在仓库下面有一个 example 文件夹,里面是一个简易的 gin 的 web server,可以安装后用这个 example 先测试下。

Roadmap

现在代码只能处理单个 project 下面的 swag,但是如果我是微服务的那种,但是我又要导入到某个一平台当做插件(要把接口都和到一个 spect 里面)。这个时候就无法满足这种场景,一个个手动贴也很烦,所以下一步就是可以生成某个微服务项目下的 OpenApi v3 spec,所有的接口都在一份 spec 里面。当然,如果除了这个方法之外还有更好的方法,欢迎分享。

相关推荐
zwjapple2 分钟前
typescript里面正则的使用
开发语言·javascript·正则表达式
小五Five3 分钟前
TypeScript项目中Axios的封装
开发语言·前端·javascript
前端每日三省5 分钟前
面试题-TS(八):什么是装饰器(decorators)?如何在 TypeScript 中使用它们?
开发语言·前端·javascript
凡人的AI工具箱18 分钟前
15分钟学 Go 第 60 天 :综合项目展示 - 构建微服务电商平台(完整示例25000字)
开发语言·后端·微服务·架构·golang
java亮小白199726 分钟前
Spring循环依赖如何解决的?
java·后端·spring
chnming198734 分钟前
STL关联式容器之map
开发语言·c++
进击的六角龙35 分钟前
深入浅出:使用Python调用API实现智能天气预报
开发语言·python
檀越剑指大厂35 分钟前
【Python系列】浅析 Python 中的字典更新与应用场景
开发语言·python
2301_8112743142 分钟前
大数据基于Spring Boot的化妆品推荐系统的设计与实现
大数据·spring boot·后端
湫ccc43 分钟前
Python简介以及解释器安装(保姆级教学)
开发语言·python