如何使用OpenAPI 3.0响应“链接"在Swagger UI中?

问题描述

我正在编写Open API 3.0规范，并尝试获取响应链接进行渲染Swagger UI v 3.18.3中.

I'm writing an Open API 3.0 spec and trying to get response links to render in Swagger UI v 3.18.3.

示例:

openapi: 3.0.0
info:
  title: Test
  version: '1.0'
tags:
  - name: Artifacts
paths:
  /artifacts:
    post:
      tags:
        - Artifacts
      operationId: createArtifact
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        201:
          description: create
          headers:
            Location:
              schema:
                type: string
                format: uri
                example: /artifacts/100
          content:
            application/json:
              schema:
                type: object
                properties:
                  artifactId:
                    type: integer
                    format: int64
          links:
            Read Artifact:
              operationId: getArtifact
              parameters:
                artifact-id: '$response.body#/artifactId'
  /artifacts/{artifact-id}:
    parameters:
      - name: artifact-id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Artifacts
      operationId: getArtifact
      responses:
        200:
          description: read
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

提供这样的链接:

这是预期的吗?我问是因为operationId在UI上公开了，而parameters被显示为JSON引用，使得看起来好像没有正确显示.我本来希望有一个超链接或某种东西可以带我到Swagger网页中的相应部分，该部分与该链接所引用的API相对应.

Is this expected? I ask because the operationId is exposed on the UI and parameters is shown as a JSON reference make it seem like something is not displaying properly. I would have expected a hyperlink or something to take me to the appropriate section in the Swagger web page that corresponds to the API being referenced by the link.

推荐答案

是的，这是Swagger UI当前呈现OAS3 links的方式. links的呈现是他们的OAS3支持积压:

Yes this is how Swagger UI currently renders OAS3 links. Rendering of links is one of the things on their OAS3 support backlog:

这篇关于如何使用OpenAPI 3.0响应“链接"在Swagger UI中?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！