openapi-generator入门及快速实践

本文最后更新于:2022年8月17日 上午

1 - 什么是openapi

这里的openapi指狭义的openapi, 即:

OpenAPI规范(以前称为Swagger规范)是一种机器可读接口文件的规范,用于描述,生成,使用和可视化RESTful Web服务。它以前是Swagger框架的一部分,在2016年成为一个单独的项目,由Linux基金会的一个开源协作项目OpenAPI Initiative监督。

目前openapi常用的规范有v2和v3, 最明显的区别在api.yml的第一行上(

1
2
swagger: "2.0"  # v2
openapi: "3.0.0" # v3

目前v3的完整规范可以参考这里

v2的完整规范可以参考这里

提供一个User服务的典型示例文件, 并带有一定的注释, 本文之后的实践部分也将基于如下的api进行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# openapi 标准版本(v2)
swagger: "2.0"
# 一些基本信息
info:
title: 'swagger test'
description: ''
version: '0.1'
termsOfService: 'http://swagger.io/terms/'
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
# 协议: "http", "https", "ws", "wss"
schemes:
- "http"
# 基本路径: 一般是<host><basePath><paths>, 如localhost:8888/api/user/save
basePath: /api
# api服务的路径与详细参数
paths:
/user/save: # 路径
post: # 请求
tags: # tag必须唯一, 用于对接口进行分类
- "User"
summary: "save user"
description: "return init password"
operationId: saveUser # 一般各种codegen工具会根据这个生成方法
produces:
- "application/json"
parameters: # 参数
- in: body
name: "user"
required: true
schema:
$ref: "#/definitions/User" # 表示引用definitions/User这个Object作为该参数
responses: # 返回值和返回值格式
200:
description: "operate success"
schema:
type: object
$ref: "#/definitions/Response"
400:
description: "operate down"
schema:
type: object
$ref: "#/definitions/Response"
get:
operationId: getUser
produces:
- "application/json"
responses:
200:
description: "get user lists"
schema:
type: array
$ref: "#/definitions/Users"

# 对各种Object作定义
definitions:
Response:
type: object
properties:
success:
type: boolean
code:
type: string
message:
type: string
data:
type: object

User:
type: object
required:
- userNumber
- userName
properties:
id:
type: integer
format: int64
userNumber:
type: string
pattern: \d{8}
userName:
type: string
pattern: ^[a-zA-Z]{1,40}$
phone:
type: string
pattern: (\d{10})?
userStatus:
type: string
operatorNumber:
type: string

Users:
type: array
items:
$ref: "#/definitions/User"

更多信息请参考其他博客和官方文档,总之openapi的规范考虑的非常全面,基本可以定义出一个api的所有详细信息,让开发不再模糊,开发者之间不再产生分歧。

2 - openapi-generator

项目地址

简单来说,openapi-generator的功能就是根据标准的api文档,生成对应的服务端或者客户端代码的工具,并且支持许多不同的语言和框架。

目前openapi-generator支持生成这些语言的代码。

和swagger codegen的比较

swagger-codegen的功能和openapi-generator几乎一致

根据openapi-generator官网所言

OpenAPI Generator is a fork of swagger-codegen between version 2.3.1 and 2.4.0.

openapi-generator是根据swagger-codegen的分叉版本, 分叉原因见

总结就是:

  1. 开发人员理念不一致
  2. 希望更快的发布和更新版本
  3. 希望进行社区驱动(openapi-generator)而不是公司驱动(swagger-codegen)

根据openhub的比较

前者更活跃一点

3 - openapi-generator-maven-plugin

openapi-generator-maven-plugin是一个openapi-generator的子项目, 同时也是java使用openapi开发客户端或者服务端的神器。

它的主要功能是在java项目构建时运行该插件, 在target中生成相应的代码, 免去手动执行cli的工作了, 并且不会影响到项目代码本身。

readme文档: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md

code talks,我基于jdk1.8openapi-generator-maven-plugin分别写了java的客户端(with feign client)和服务端(with springboot)的最小示例,供参考学习。

demo

项目地址


openapi-generator入门及快速实践
https://blog.roccoshi.top/posts/12285/
作者
RoccoShi
发布于
2022年7月21日
许可协议