将 OpenApi Paths 拆分为多个路径定义文件
Split OpenApi Paths into multiple path definition files
我想更容易地将我的路径(很多)拆分到它们自己的文件中。
假设我有两条主路径 /user
和 /anotherPath
,还有几个子路径。现在我有一个 OpenApi 规范文件,其路径被引用到一个索引文件,该文件包含对每个路径的引用。用它的参考作品定义每个路径,但写起来很笨拙。
我想要这样的东西:
openapi.json
{
...
"paths": {
"$ref": "paths/index.json"
}
...
}
paths/index.json
{
"/user": { // and everything that comes after user, e.g. /user/{userId}
"$ref": "./user-path.json"
},
"/anotherPath": { // and everything that comes after anotherPath, e.g. /anotherPath/{id}
"$ref": "./anotherPath-path.json"
}
}
paths/user-path.json
{
"/user": {
"get": {...}
},
"/user/{userId}": {
"get": {...}
}
}
paths/anotherPath-path.json
{
"/anotherPath": {
"get": {...}
},
"/anotherPath/{id}": {
"get": {...}
}
}
这样,每当我向 /user
或 /anotherPath
添加另一个路径时,我都可以简单地编辑它们各自的路径文件,例如paths/user-path.json.
EDIT1:显然,这个话题已经在讨论中了。对于任何感兴趣的人:https://github.com/OAI/OpenAPI-Specification/issues/417。顺便说一下,我知道 $ref
对 paths
对象无效,但是一旦弄清楚如何正确拆分,这可能就不再需要了。
OpenAPI 没有子路径/嵌套路径的概念,每个路径都是一个单独的实体。 paths
关键字本身不支持$ref
,只支持个别路径.
鉴于您的 user-path.json 和 anotherPath-path.json 文件,引用路径的正确方法定义如下:
{
...
"paths": {
"/user": {
"$ref": "paths/user-path.json#/~1user" // ~1user is /user escaped according to JSON Pointer and JSON Reference rules
},
"/user/{id}": {
"$ref": "paths/user-path.json#/~1user~1%7Bid%7D" // ~1user~1%7Bid%7D is /user/{id} escaped
},
"/anotherPath": {
"$ref": "paths/anotherPath-path.json#/~1anotherPath" // ~1anotherPath is /anotherPath escaped
},
"/anotherPath/{id}": {
"$ref": "paths/anotherPath-path.json#/~1anotherPath~1%7Bid%7D" // ~1anotherPath~1%7Bid%7D is /anotherPath/{id} escaped
}
}
...
}
YAML 版本:
paths:
/user:
$ref: "paths/user-path.json#/~1user"
/user/{id}:
$ref: "paths/user-path.json#/~1user~1%7Bid%7D"
/anotherPath:
$ref: "paths/anotherPath-path.json#/~1anotherPath"
/anotherPath/{id}:
$ref: "paths/anotherPath-path.json#/~1anotherPath~1%7Bid%7D"
如果你想在任意地方使用 $ref
(除了 OAS 允许 $refs 的地方),你必须使用可以解析任意 $refs 的 parser/tool 预处理你的定义;这将为您提供一个有效的 OpenAPI 文件,该文件可与兼容 OpenAPI 的工具一起使用。一种这样的预处理工具是 json-refs, you can find an example of pre-processing here.
我想更容易地将我的路径(很多)拆分到它们自己的文件中。
假设我有两条主路径 /user
和 /anotherPath
,还有几个子路径。现在我有一个 OpenApi 规范文件,其路径被引用到一个索引文件,该文件包含对每个路径的引用。用它的参考作品定义每个路径,但写起来很笨拙。
我想要这样的东西:
openapi.json
{
...
"paths": {
"$ref": "paths/index.json"
}
...
}
paths/index.json
{
"/user": { // and everything that comes after user, e.g. /user/{userId}
"$ref": "./user-path.json"
},
"/anotherPath": { // and everything that comes after anotherPath, e.g. /anotherPath/{id}
"$ref": "./anotherPath-path.json"
}
}
paths/user-path.json
{
"/user": {
"get": {...}
},
"/user/{userId}": {
"get": {...}
}
}
paths/anotherPath-path.json
{
"/anotherPath": {
"get": {...}
},
"/anotherPath/{id}": {
"get": {...}
}
}
这样,每当我向 /user
或 /anotherPath
添加另一个路径时,我都可以简单地编辑它们各自的路径文件,例如paths/user-path.json.
EDIT1:显然,这个话题已经在讨论中了。对于任何感兴趣的人:https://github.com/OAI/OpenAPI-Specification/issues/417。顺便说一下,我知道 $ref
对 paths
对象无效,但是一旦弄清楚如何正确拆分,这可能就不再需要了。
OpenAPI 没有子路径/嵌套路径的概念,每个路径都是一个单独的实体。 paths
关键字本身不支持$ref
,只支持个别路径
鉴于您的 user-path.json 和 anotherPath-path.json 文件,引用路径的正确方法定义如下:
{
...
"paths": {
"/user": {
"$ref": "paths/user-path.json#/~1user" // ~1user is /user escaped according to JSON Pointer and JSON Reference rules
},
"/user/{id}": {
"$ref": "paths/user-path.json#/~1user~1%7Bid%7D" // ~1user~1%7Bid%7D is /user/{id} escaped
},
"/anotherPath": {
"$ref": "paths/anotherPath-path.json#/~1anotherPath" // ~1anotherPath is /anotherPath escaped
},
"/anotherPath/{id}": {
"$ref": "paths/anotherPath-path.json#/~1anotherPath~1%7Bid%7D" // ~1anotherPath~1%7Bid%7D is /anotherPath/{id} escaped
}
}
...
}
YAML 版本:
paths:
/user:
$ref: "paths/user-path.json#/~1user"
/user/{id}:
$ref: "paths/user-path.json#/~1user~1%7Bid%7D"
/anotherPath:
$ref: "paths/anotherPath-path.json#/~1anotherPath"
/anotherPath/{id}:
$ref: "paths/anotherPath-path.json#/~1anotherPath~1%7Bid%7D"
如果你想在任意地方使用 $ref
(除了 OAS 允许 $refs 的地方),你必须使用可以解析任意 $refs 的 parser/tool 预处理你的定义;这将为您提供一个有效的 OpenAPI 文件,该文件可与兼容 OpenAPI 的工具一起使用。一种这样的预处理工具是 json-refs, you can find an example of pre-processing here.