news 2026/4/15 10:05:03

OpenAPITools使用——入门介绍与生成spring controller代码

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
OpenAPITools使用——入门介绍与生成spring controller代码

总览

以往web开发中，编写controller层的conVO对象代码占据了大量时间，如果我们能直接用接口yaml文件生成这些对象就好了，这样我们编写的yaml文件可以直接生成controller层以及VO对象，我们也可以把yaml文件直接提供给调用方，生成http客户端代码发起服务调用。本工程提供了利用openapitools利用yaml文件直接生成controller代码以及httpclient客户端，符合API-First开发理念。

什么是API-First开发理念

API-First（API 优先）是一种以 API 为核心驱动的软件开发模式—— 在编写任何业务代码前，先设计、定义并冻结 API 规范（如 OpenAPI/Swagger 规范），再以该规范为 “契约”，同步推进前后端、跨语言（如 Java/C++）开发，最终所有模块通过统一 API 对接。

简单说：先定 “接口契约”，再写代码，而非传统 “先写后端代码，再凑接口文档，最后前端适配” 的模式。

OpenAPITools介绍

OpenAPI Generator 能够根据 OpenAPI 规范（同时支持 2.0 和 3.0 版本），自动生成 API 客户端库（SDK 生成）、服务端桩代码（接口骨架）、文档及配置文件。OpenAPITools主页

OpenAPI Generator快速入门

本章节我们将演示如何通过一个swagger的yaml接口文件生成controller以及okhttp/feign等客户端代码。使用jdk21

项目已在github上开源
https://github.com/zjurenjie/java-openapi-generator

新建项目工程

项目工程结构如下：

|---java-openapi-generator|---pom.xm# 父pom文件，定义三方件的依赖版本|---java-openapi-controller# 服务端模块，生成controller层代码|---src/main/java# 服务端代码|---src/main/resource# 资源文件|---openapi|---v1|---openapi.yaml# 接口yaml，用于生成服务端controller与客户端代码|---java-openapi-sdk# 客户端模块，生成okhttp/feign等客户端代码

配置maven依赖

测试yaml文件
这里我们可以使用OpenAPI Generator样例中的yaml示例也可以使用自己已经写好的yaml，这里使用OpenAPI Generator样例中的ping some object示例并加tag为curl的相关方法
OpenAPI Generator样例
openapi:3.0.1info:title:ping some objectversion:"1.0"servers:-url:http://localhost:8082/tags:-ping-curlpaths:/ping:get:operationId:getPingparameters:-description:ID of pet that needs to be updatedexplode:truein:queryname:petIdrequired:trueschema:format:int64type:integerstyle:formrequestBody:content:application/x-www-form-urlencoded:schema:$ref:"#/components/schemas/getPing_request"responses:"200":content:application/json:schema:$ref:"#/components/schemas/SomeObj"description:OKtags:-pingx-streaming:truex-group-parameters:truex-content-type:application/x-www-form-urlencodedx-accepts:-application/jsonpost:operationId:postPingrequestBody:content:application/json:schema:$ref:"#/components/schemas/SomeObj"responses:"200":content:application/json:schema:$ref:"#/components/schemas/SomeObj"description:OKtags:-pingx-streaming:truex-content-type:application/jsonx-accepts:-application/json/curl:get:operationId:getCurlparameters:-description:ID of pet that needs to be updatedexplode:truein:queryname:petIdrequired:trueschema:format:int64type:integerstyle:formrequestBody:content:application/x-www-form-urlencoded:schema:$ref:"#/components/schemas/getCurl_request"responses:"200":content:application/json:schema:$ref:"#/components/schemas/SomeObj"description:OKtags:-curlx-streaming:truex-group-parameters:truex-content-type:application/x-www-form-urlencodedx-accepts:-application/jsonpost:operationId:postCurlrequestBody:content:application/json:schema:$ref:"#/components/schemas/SomeObj"responses:"200":content:application/json:schema:$ref:"#/components/schemas/SomeObj"description:OKtags:-pingx-streaming:truex-content-type:application/jsonx-accepts:-application/jsoncomponents:schemas:SomeObj:example:name:nameactive:true$_type:SomeObjIdentifierid:0type:typeproperties:$_type:default:SomeObjIdentifierenum:-SomeObjIdentifiertype:stringid:format:int64type:integername:type:stringactive:type:booleantype:type:stringtype:objectSimpleOneOf:oneOf:-type:string-type:integergetPing_request:properties:name:description:Updated name of the pettype:stringstatus:description:Updated status of the pettype:stringtype:objectgetCurl_request:properties:name:description:Updated name of the pettype:stringstatus:description:Updated status of the pettype:stringtype:object
使用maven插件生成服务端代码
openapi-generator-maven-plugin官网指导
https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md
工程中配置如下：使用maven-clean-plugin插件自动清理生成的文件，使用openapi-generator-maven-plugin生成服务端代码
<build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-clean-plugin</artifactId><configuration><filesets><fileset><directory>${project.basedir}/src/main/java/org/org/numb/openapi/generator/gen</directory></fileset></filesets></configuration></plugin><plugin><groupId>org.openapitools</groupId><artifactId>openapi-generator-maven-plugin</artifactId><!-- RELEASE_VERSION --><version>${openapi-generator-maven-plugin.version}</version><executions><execution><id>generate-controller</id><phase>generate-resources</phase><goals><goal>generate</goal></goals><configuration><!-- 1. 关键配置：OpenAPI 规范文件（本地路径或 URL） --><inputSpec>${project.basedir}/src/main/resources/openapi/v1/openapi.yaml</inputSpec><!-- 或从远程 API 获取规范：<inputSpec>http://localhost:8080/v3/api-docs</inputSpec> --><!-- 2. 生成代码目标语言（必填，支持 50+ 语言，小写） --><!-- 常用语言：java、python、go、typescript-axios、php、csharp 等 --><generatorName>spring</generatorName><library>spring-boot</library><!-- 3. 输出目录（生成的代码存放位置，默认 src/main/java） --><output>${project.basedir}</output><!-- 4. 包配置（Java 语言专属，指定生成代码的包名） --><packageName>org.org.numb.openapi.generator.gen</packageName><!-- 根包名 --><apiPackage>org.org.numb.openapi.generator.gen.delegate</apiPackage><!-- API 操作类包名 --><modelPackage>org.org.numb.openapi.generator.gen.model</modelPackage><!-- 数据模型包名 --><!-- 5. 额外配置（可选，根据语言自定义） --><generateModelTests>false</generateModelTests><!-- 不生成模型测试代码 --><generateApiTests>false</generateApiTests><!-- 不生成API测试代码 --><openapiGeneratorIgnoreList>pom.xml</openapiGeneratorIgnoreList><configOptions><interfaceOnly>true</interfaceOnly><dateLibrary>java21</dateLibrary><!-- 日期处理用 Java8 LocalDate --><useJakartaEe>true</useJakartaEe><!-- 是否使用 Jakarta EE（默认 false，用 Java EE） --><useBeanValidation>true</useBeanValidation><delegatePattern>true</delegatePattern><useSpringController>false</useSpringController><useOneOfInterfaces>true</useOneOfInterfaces></configOptions><!-- 6. 忽略已存在的文件（避免覆盖手动修改的代码，可选） --><ignoreFileOverride>${project.basedir}/</ignoreFileOverride></configuration></execution></executions></plugin></plugins></build>
configuration常用配置
  • inputSpec：OpenAPI 规范文件（本地路径或 URL）
  • generatorName：生成代码目标语言，当生成服务端代码时使用spring，library支持spring-boot、spring-cloud等标签
  • library：服务端常用spring-boot、spring-cloud。spring-boot为生成controller代码，如果指定spring-cloud还会生成feign的客户端接口
  • output：输出目录（生成的代码存放位置，默认 src/main/java）
  • packageName：根包名配置（Java 语言专属，指定生成代码的包名）
  • apiPackage：API 操作类包名
  • modelPackage： 数据模型包名
  • generateModelTests：不生成模型测试代码
  • generateApiTests：不生成API测试代码
  • openapiGeneratorIgnoreList：不生成的文件列表，这里可以配置pom.xml，让我们可以重新定义依赖组件的版本，不由openapi-tools控制
configOptions常用配置
  • interfaceOnly: 只生成controller接口代码，不生成实现类
  • useJakartaEe：是否使用 Jakarta EE（默认 false，用 Java EE），使用jdk17/jdk21与springboot3.x设置为true
  • useBeanValidation：是否开启bean校验
  • delegatePattern：是否使用代理模式生成服务端代码
spring服务端更多配置参考：
https://openapi-generator.tech/docs/generators/spring/#config-options
客户端配置与服务端配置不同，可根据生成代码需求按照generator类型分类查找
https://openapi-generator.tech/docs/generators/









版权声明:

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！













网站建设
2026/4/8 4:35:57



解锁IDM长期使用：三步掌握注册表配置技术


解锁IDM长期使用&#xff1a;三步掌握注册表配置技术 【免费下载链接】IDM-Activation-Script IDM Activation & Trail Reset Script   项目地址: https://gitcode.com/gh_mirrors/id/IDM-Activation-Script     
还在为IDM试用期结束而烦恼&#xff1f;现在你只需要掌握一…






作者头像
李华














网站建设
2026/4/13 11:47:29



四步构建专属特斯拉数据驾驶舱


您是否曾想过&#xff0c;那些隐藏在特斯拉车辆深处的数据究竟蕴藏着怎样的价值&#xff1f;从驾驶习惯的优化密码到电池健康的真实状态&#xff0c;TeslaMate数据监控平台为您打开了一扇通往深度车辆认知的大门。这个开源的自托管方案让每一位技术爱好者都能拥有专属的数据分析…






作者头像
李华














网站建设
2026/4/14 4:30:15



v-scale-screen初学者指南：图解说明关键配置项


如何用v-scale-screen实现嵌入式界面的多屏适配&#xff1f;一文讲透关键配置与实战技巧你有没有遇到过这样的问题&#xff1a;在开发一块 800480 的触摸屏时&#xff0c;UI 设计得完美无瑕&#xff0c;但换到一块 1024600 或者竖屏设备上后&#xff0c;按钮错位、文字溢出、点…






作者头像
李华














网站建设
2026/4/11 1:51:39



Dify如何实现上下文感知的内容生成？


Dify如何实现上下文感知的内容生成&#xff1f;
在企业智能化转型的浪潮中&#xff0c;一个常见的挑战浮现出来&#xff1a;如何让大语言模型&#xff08;LLM&#xff09;不只是“知道很多”&#xff0c;而是真正“理解语境”&#xff1f;许多团队尝试直接调用OpenAI或本地部署…






作者头像
李华














网站建设
2026/4/7 8:41:51



手把手教程：如何看懂STLink接口引脚图并正确接线


手把手教你识破STLink接线迷局&#xff1a;从引脚图到零错误连接你有没有过这样的经历&#xff1f;手握STLink调试器&#xff0c;线也插了&#xff0c;IDE打开了&#xff0c;点击“Debug”却弹出一句冰冷的提示&#xff1a;“Cannot connect to target.”更糟的是&#xff0c;某…






作者头像
李华














网站建设
2026/4/11 3:23:16



Bongo Cat终极选择指南：三大模型对比帮你找到最佳桌面伙伴


Bongo Cat终极选择指南&#xff1a;三大模型对比帮你找到最佳桌面伙伴 【免费下载链接】BongoCat 让呆萌可爱的 Bongo Cat 陪伴你的键盘敲击与鼠标操作&#xff0c;每一次输入都充满趣味与活力&#xff01;   项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat     
在漫…






作者头像
李华