Swagger工程化实践

1、从零开始新增API

1.1、编写Swagger API并保存为api.yaml到本地

打开Swagger editor API文档编辑工具（通过单击下面社区链接）
社区：https://editor.swagger.io
API编写规范参照：Open API规范（https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md）

1.2、下载swagger-codegen-cli.jar

地址：https://github.com/XiaotaoYi/spring/blob/master/spring-boot-swagger/swagger-codegen-cli.jar

1.3、准备api-codegen-config.json

image.png

使用： https://github.com/XiaotaoYi/spring/blob/master/spring-boot-swagger/api-codegen-config.json

文件中的参数值需要改变。

apiPackage：生成Controller的完整包名。

groupId：maven项目的groupId。

artifactId：maven项目的artifactId。

artifactVersion：maven项目的版本。

modelPackage：生成API返回模型的完整包名。

basePackage：项目的包名。

configPackage：生成配置类的完整包名。

1.4、用命令生成初始项目

java -jar swagger-codegen-cli.jar generate -i api.yaml -l spring -o example -c api-codegen-config.json

其中：-o 为output path

2、基于已有工程修改API

2.1 打开Swagger editor API文档编辑工具（通过单击下面链接）

社区：https://editor.swagger.io/

2.2 从工程中复制API定义到swagger editor中（复制如图api.yaml中内容）

image.png

2.3 编辑API文档

参照项：

1）已有API定义

2）Open API规范（https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md）

2.4 使用新的API定义去覆盖项目api.yaml

2.5 在Run/Debug Configuration窗口中新建或编辑一个如下图的Maven配置，并启动

image.png

重要说明：

1）使用spring-boot:run命令行去启动spring boot 程序（这样会自动根据API.yaml生成新的API接口代码，保持开发基于最新代码）

2）启动过程中，会自动根据API.yaml生成新的API接口代码（包括接口类或模型）

3）接口类和模型不能被手工添加和修改，只能靠swagger-codegen-maven-plugin自动生成

4）Fix相应编译错误（可能API实现类需要根据新的API进行改写）