Блог

Я пишу спецификацию Open API 3.0 и пытаюсь получить ссылки на ответ для рендеринга в пользовательском интерфейсе Swagger версии 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 это отображается в пользовательском интерфейсе и parameters отображается как ссылка JSON, из-за чего кажется,что что-то не отображается должным образом. Я ожидал, что гиперссылка или что-то еще приведет меня к соответствующему разделу на веб-странице Swagger, который соответствует API, на который ссылается ссылка.

Да, именно так пользовательский интерфейс Swagger в настоящее время отображает OAS3 links . Рендеринг links является одним из пунктов в их отставании в поддержке OAS3:

Отставание в поддержке OAS 3.0
Это билет для сбора данных для функций спецификации OAS3, которые еще не поддерживаются Swagger-UI.
…
[ ] Ссылки не могут быть использованы для выполнения другой операции
[ ] Серверы канального уровня недоступны для выполнения запросов