将OpenApi路径拆分为多个路径定义文件 [英] Split OpenApi Paths into multiple path definition files

问题描述

我想更轻松地将路径(很多)分割成自己的文件.

I want to split my paths (which are quite many) more easily into their own files.

比方说，我有两个主要路径/user和/anotherPath以及几个子路径.现在，我有了一个OpenApi规范文件，该文件的路径被引用到一个索引文件，该文件包含对每个路径的引用.用参考定义每个路径都可以，但是编写起来很笨拙.

Let's say I've got two major paths /user and /anotherPath with several subpaths. Now I've got an OpenApi spec file, whose paths are being referenced to an index file which holds references to each paths. Defining EVERY path with its' reference works, but is clumsy to write.

我想要这样的东西:

openapi.json

openapi.json

{
...
  "paths": {
    "$ref": "paths/index.json"
  }
...
}

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

paths/user-path.json

{
  "/user": {
    "get": {...}
  },
  "/user/{userId}": {
    "get": {...}
  }
}

paths/anotherPath-path.json

paths/anotherPath-path.json

{
  "/anotherPath": {
    "get": {...}
  },
  "/anotherPath/{id}": {
    "get": {...}
  }
}

这样，每当我向/user或/anotherPath添加另一个路径时，我都可以简单地编辑它们各自的路径文件，例如路径/user-path.json.

This way, whenever I add another path to /user or /anotherPath, I can simply edit their respective path file, e.g. paths/user-path.json.

显然，该主题已经在讨论中.对于任何有兴趣的人: https ://github.com/OAI/OpenAPI-Specification/issues/417 .顺便说一句，我知道$ref对paths对象无效，但是一旦弄清楚如何正确分割，就可能不再需要了.

Apparently, this topic is being discussed already.. For anyone interested: https://github.com/OAI/OpenAPI-Specification/issues/417 . By the way, I know that a $ref is not valid for the paths Object, but once figuring out how to properly split, this may not be necessary anymore.

推荐答案

OpenAPI没有子路径/嵌套路径的概念，每个路径都是一个单独的实体. paths关键字本身不支持$ref，仅可以引用单个路径.

OpenAPI does not have a concept of sub-paths / nested paths, each path is an individual entity. The paths keyword itself does not support $ref, only individual paths can be referenced.

给出您的 user-path.json 和 anotherPath-path.json 文件，引用路径定义的正确方法如下:

Given your user-path.json and anotherPath-path.json files, the correct way to reference path definitions is as follows:

{
  ...
  "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"

如果要在任意地方(OAS允许$ ref的地方除外)使用$ref，则必须使用可以解析任意$ ref的解析器/工具对定义进行预处理.这将为您提供可与兼容OpenAPI的工具一起使用的有效OpenAPI文件.这样的预处理工具之一是 json-refs ，您可以找到预处理的示例此处.

If you want to use $ref in arbitrary places (other than where OAS allows $refs), you'll have to pre-process your definition using a parser/tool that can resolve arbitrary $refs; this will give you a valid OpenAPI file that can be used with OpenAPI-compliant tools. One such pre-processing tool is json-refs, you can find an example of pre-processing here.

这篇关于将OpenApi路径拆分为多个路径定义文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！