是否可以在 OpenAPI 3 中引用单个路径和方法? [英] Is it possible to reference a single path and method in OpenAPI 3?

问题描述

假设我有一个描述 API Foo 的 OpenAPI 3 文档，如下所示:

openapi: 3.0.0信息:版本:'1'书名:福路径:/foo:得到:回应:200:描述:阿福邮政:回应:201:描述:Foo 创建

在 API Bar 的另一个 OpenAPI 文档中，我想仅引用 API Foo<中的 GET/foo 操作/代码>.OpenAPI 文档稍微介绍了引用整个路径.但是，如果我执行以下操作:

openapi: 3.0.0信息:版本:'1'标题栏路径:/foo:$ref: 'foo.yaml#/paths/~1foo'

我很自然地同时获得了 API Bar 中的 GET 和 POST，因为只引用了路径，而不是方法.

我试过了:

openapi: 3.0.0信息:版本:'1'标题栏路径:/foo:得到:$ref: 'foo.yaml#/paths/~1foo/get'

但这会导致错误，例如 should NOT have additional properties additionalProperty: $ref 和 should have required property 'responses' missingProperty: answers 在各种工具中，所以它没有'似乎支持.

有没有办法做到这一点?我应该注意到，真正的请求要复杂得多，因此需要重复数据删除.如果可能的话，我想避免用单独的 $ref s 填充 get 的许多子对象.

解决方案

OpenAPI 没有办法 $ref 单个操作 (get/post/etc.)，你只能$ref整个路径.

您可以在 OpenAPI 规范存储库中提出语法增强:
https://github.com/OAI/OpenAPI-Specification/issues

Suppose I have an OpenAPI 3 document describing API Foo as follows:

openapi: 3.0.0
info:
  version: '1'
  title: Foo
paths:
 /foo:
  get:
    responses:
      200:
        description: A Foo
  post:
    responses:
      201:
        description: Foo created

In another OpenAPI document for API Bar, I would like to reference only the GET /foo operation from API Foo. The OpenAPI docs talk a little about referencing a whole path. However, if I do the following:

openapi: 3.0.0
info:
  version: '1'
  title: Bar
paths:
 /foo:
  $ref: 'foo.yaml#/paths/~1foo'

I naturally get both the GET and the POST in API Bar, since only the path is referenced, not the method.

I tried this:

openapi: 3.0.0
info:
  version: '1'
  title: Bar
paths:
 /foo:
   get:
     $ref: 'foo.yaml#/paths/~1foo/get'

But this gives errors like should NOT have additional properties additionalProperty: $ref and should have required property 'responses' missingProperty: responses in various tools, so it doesn't seem to be supported.

Is there a way to accomplish this? I should note that the real request is much more complicated, hence the desire to de-duplicate. If possible I would like to avoid filling in many child objects of get with individual $refs.

解决方案

OpenAPI doesn't have a way to $ref an individual operation (get/post/etc.), you can only $ref an entire path.

You can propose syntax enhancements in the OpenAPI Specification repository:
https://github.com/OAI/OpenAPI-Specification/issues

这篇关于是否可以在 OpenAPI 3 中引用单个路径和方法?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！