在 $ref 打开时引用远程“响应”和“参数”api 3.0

Question

我正在 swaggerhub 上创建一个组织良好的 OAS3 swagger 文档。对于每个端点，我都写了所有可能的答案，如 200、201、204、400、401、403、404、500 等。此外，所有方法都有默认参数，如 X-Language-Code 等。我所处的位置使得我现在使用的响应、模型和参数开始在每个文件中重复出现。经过一些研究，我了解到我可以创建一个域和对它们的远程绝对 url 引用。当我像这样远程使用“定义”时没有错误：

/example:
    get:
        #some other informations here
        responses:
            200:
                description: 'example description'
                content:
                    application/json:
                        schema:
                            $ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'

但是，显然您不能在 responses 或 400 等下方使用 $ref 关键字。像这样的关键字：

This one not getting error but not rendering the remote reference

responses:
    400:
        $ref: 'https://remote.example/url/2.0#/responses/Error400'

或者这个：

This one gives error

responses:
    $ref: 'https://remote.example/url/2.0#/responses'

甚至，我不能像我预期的那样使用'parameters':

/example:
    get:
        parameters:
            - languageCode:
                $ref: 'https://remote.example/url/2.0#/parameters/languageCode'

/example:
    get:
        parameters:
            - $ref: 'https://remote.example/url/2.0#/parameters/'

我不想重写每个文档下面的所有参考定义。我对使用和引用“域”感到困惑。有人可以解释或参考有关这种情况的文档，因为我找不到任何关于它的文档。

Answer 1

更新： OpenAPI SwaggerHub 现在支持 3.0 域。

截至 2018 年 12 月，SwaggerHub 域仅支持 OpenAPI 2.0 语法，但不支持 OpenAPI 3.0。 OpenAPI 3.0 和 2.0 对参数、响应等使用略有不同的语法，这意味着您不能从 OAS3 API 定义中引用 OAS2 域。

解决方法是在 SwaggerHub 中创建另一个 OpenAPI 3.0 API 并将其用作 "domain"。您需要添加一个带有 openapi: 3.0.0 的虚拟 header，info 部分和空的 paths: {} 以使验证器满意。

openapi: 3.0.0
info:
  title: Common components
  version: 1.0.0
paths: {}

# Put your common components here:
components:
  schemas:
    ...
  parameters:
    ...
  responses:
    ...

然后您可以使用通常的 $ref 语法从这个 "domain" 引用组件：

$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'

确保 $refs 中的主机名是 API.swaggerhub.com（不是 APP.swaggerhub.com）并且 link 包含 /apis/（不是 /domains/）。

在 $ref 打开时引用远程“响应”和“参数”api 3.0

Referencing remote 'response's and 'parameter's on $ref open api 3.0

swagger

openapi

swaggerhub