ICode9

精准搜索请尝试: 精确搜索
首页 > 其他分享> 文章详细

openapi-generator教程

2022-07-07 16:39:05  阅读:169  来源: 互联网

标签:npm 教程 generator 生成 yaml 文档 openapi


一、简介

Github地址:https://github.com/OpenAPITools/openapi-generator

官网文档: https://openapi-generator.tech/docs/installation

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

在Github上,openapi-generator项目拥有Star 10k,Contributors 近2000,是一个非常优秀的项目,支持多种安装方式,以及支持通过yaml、JSON文件生成几十种客户端和服务端语言,生成的SDK代码十分优雅,代码中也包含了注释,非常容易阅读。同时,还生成了非常详细的markdown文档。

二、安装

openapi-generator支持多种安装方式:npm、Homebrew、Docker、JAR、Bash Launcher Script

详细的安装文档地址:https://openapi-generator.tech/docs/installation

下面以npm安装方式简要说明一下

npm支持的平台有Linux、macOS、Windows,需要本机已经安装了node.js

使用npm安装openapi-generator非常简单,就三行命令

# 安装脚手架
npm install @openapitools/openapi-generator-cli -g
# 设置使用的版本
openapi-generator-cli version-manager set 5.1.0
# 添加依赖
npm install @openapitools/openapi-generator-cli -D

 

 

 

 

三、使用

下面以官方提供的yaml文件生成一个java sdk做示例

https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml 

# 官方提供openapi-generator命令格式如下
npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g ruby -o /tmp/test/
# -i petstore.yaml 表示要根据哪个文档生成,支持yaml和json
# -g ruby          表示生成ruby client
# -o /tmp/test/    指定存放的地址

所以,根据我们下载下来的petstore.yaml,我们生成一个java项目

npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g java -o G:\openapi-generator\sdk

 

 

 

 

 

 通过IDEA打开生成的项目,成功编译通过以及运行成功,项目提供了优雅的代码以及单元测试,同时还提供了markdown文档告诉你怎么编译项目、如何使用sdk以及api接口文档,功能十分强大

 

 

 

 

 

 

 

 

 

 

 

四、支持语言

在官方文档中,支持了几乎常见的所有语言,你所知道的java、csharp、csharp-netcore、python、go、c、c++、php等等都能支持,详细文档如下:https://openapi-generator.tech/docs/generators 

五、建议

从上面教程,我们可以使用yaml或者json文件以标准的格式生成多语言sdk,一般而言,我们在开发api接口的时候,最好引入swagger中间件,并且在编写代码的时候加入接口描述,这样生成的swagger.json也包含了api的描述信息,我们通过swagger.json直接生成多语言sdk,直接省去了我们编写sdk,通过一行命令就直接生成想要的语言,节省100%的工作,而且通过openapi-generator还帮我们写好了markdown文档,简直不要太舒服。

标签:npm,教程,generator,生成,yaml,文档,openapi
来源: https://www.cnblogs.com/telwanggs/p/16455129.html

本站声明: 1. iCode9 技术分享网(下文简称本站)提供的所有内容,仅供技术学习、探讨和分享;
2. 关于本站的所有留言、评论、转载及引用,纯属内容发起人的个人观点,与本站观点和立场无关;
3. 关于本站的所有言论和文字,纯属内容发起人的个人观点,与本站观点和立场无关;
4. 本站文章均是网友提供,不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属;如您发现该文章侵犯了您的权益,可联系我们第一时间进行删除;
5. 本站为非盈利性的个人网站,所有内容不会用来进行牟利,也不会利用任何形式的广告来间接获益,纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

专注分享技术,共同学习,共同进步。侵权联系[81616952@qq.com]

Copyright (C)ICode9.com, All Rights Reserved.

ICode9版权所有