news 2026/3/11 7:31:19

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/3/10 19:11:51



palera1n越狱工具深度解析：解锁iOS设备潜力的关键技术


在iOS生态系统中&#xff0c;palera1n越狱工具以其独特的技术架构和广泛的兼容性&#xff0c;为A8至A11芯片设备用户提供了突破系统限制的全新途径。这款专为iOS 15.0及以上版本设计的越狱方案&#xff0c;不仅支持iPhone 6s到iPhone X全系列设备&#xff0c;还兼容多款iPad和A…






作者头像
李华














网站建设
2026/3/10 3:32:31



IDM激活脚本完整指南：免费解锁永久试用期


IDM激活脚本完整指南&#xff1a;免费解锁永久试用期 【免费下载链接】IDM-Activation-Script IDM Activation & Trail Reset Script   项目地址: https://gitcode.com/gh_mirrors/id/IDM-Activation-Script     
还在为Internet Download Manager试用期结束而发愁&#xf…






作者头像
李华














网站建设
2026/3/9 1:13:13



Dify如何实现基于规则引擎的决策判断？


Dify如何实现基于规则引擎的决策判断&#xff1f;
在AI应用从“能说会道”走向“能做会判”的今天&#xff0c;一个核心问题日益凸显&#xff1a;我们该如何让大语言模型&#xff08;LLM&#xff09;不只是生成流畅文本&#xff0c;而是真正参与业务流程、做出可解释且可控的决…






作者头像
李华














网站建设
2026/3/10 4:22:08



Nucleus Co-op：单机分屏游戏的终极完整配置教程


还在为单机游戏无法与朋友本地同屏游玩而烦恼吗&#xff1f;Nucleus Co-op 这款革命性的开源工具将彻底改变您的游戏体验。通过创新的虚拟多实例技术&#xff0c;让您在同一台电脑上仅需一个游戏副本就能畅享分屏对战乐趣&#xff01; 【免费下载链接】splitscreenme-nucleus N…






作者头像
李华














网站建设
2026/3/9 13:17:32



Keil C51编写抗干扰控制程序：工业级实践


Keil C51编写抗干扰控制程序&#xff1a;工业级实践在工业现场&#xff0c;你有没有遇到过这样的情况&#xff1f;一台温控仪表明明昨天还工作正常&#xff0c;今天却突然“发疯”——加热继电器不停通断&#xff0c;设定值莫名其妙变成0&#xff0c;通信接口彻底失联。重启&am…






作者头像
李华














网站建设
2026/3/8 22:00:32



Dify镜像支持CORS配置实现跨域调用


Dify镜像支持CORS配置实现跨域调用
在现代AI应用开发中&#xff0c;前后端分离已成为主流架构模式。随着Dify这类低代码大模型应用平台的普及&#xff0c;越来越多企业选择将其部署于私有环境&#xff0c;而前端则运行在独立域名下——这种解耦带来了灵活性&#xff0c;也引入了…






作者头像
李华