apidom-reference: OpenAPI 3.1.0 dereference issue

[char0n]

Fixture

openapi: 3.1.0
info:
  title: Swagger Petstore - OpenAPI 3.1
  description: |-
    This is a sample Pet Store Server based on the OpenAPI 3.1 specification.
    You can find out more about
    Swagger at [http://swagger.io](http://swagger.io).
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0 AND (MIT OR GPL-2.0-only)
    identifier: Apache-2.0 AND (MIT OR GPL-2.0-only)
  version: "1.0"
  summary: Pet Store 3.1
  x-namespace: swagger
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
- url: /api/v31
tags:
- name: pet
  description: Everything about your Pets
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: store
  description: Access to Petstore orders
  externalDocs:
    description: Find out more about our store
    url: http://swagger.io
- name: user
  description: Operations about user
paths:
  /pet:
    put:
      tags:
      - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      operationId: updatePet
      requestBody:
        description: Pet object that needs to be updated in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in JSON Format
              required:
              - id
              writeOnly: true
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in XML Format
              required:
              - id
              writeOnly: true
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in XML Format
                readOnly: true
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in JSON Format
                readOnly: true
        "400":
          description: Invalid ID supplied
        "404":
          description: Pet not found
        "405":
          description: Validation exception
      security:
      - petstore_auth:
        - write:pets
        - read:pets
    post:
      tags:
      - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in JSON Format
              required:
              - id
              writeOnly: true
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in XML Format
              required:
              - id
              writeOnly: true
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in XML Format
                readOnly: true
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in JSON Format
                readOnly: true
        "405":
          description: Invalid input
      security:
      - petstore_auth:
        - write:pets
        - read:pets
  /pet/{petId}:
    get:
      tags:
      - pets
      summary: Find pet by ID
      description: Returns a pet when 0 < ID <= 10.  ID > 10 or nonintegers will simulate
        API error conditions
      operationId: getPetById
      parameters:
      - name: petId
        in: path
        description: ID of pet that needs to be fetched
        required: true
        schema:
          type: integer
          format: int64
          description: param ID of pet that needs to be fetched
          exclusiveMaximum: 10
          exclusiveMinimum: 1
      responses:
        default:
          description: The pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in JSON format
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in XML format
        "400":
          description: Invalid ID supplied
        "404":
          description: Pet not found
      security:
      - petstore_auth:
        - write:pets
        - read:pets
      - api_key: []
components:
  schemas:
    Category:
      description: Category
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: Category
    Pet:
      $schema: https://json-schema.org/draft/2020-12/schema
      description: Pet
      properties:
        id:
          type: integer
          format: int64
          example: 10
        category:
          $ref: '#/components/schemas/Category'
          description: Pet Category
        name:
          type: string
          example: doggie
        photoUrls:
          type: array
          items:
            type: string
            xml:
              name: photoUrl
          xml:
            wrapped: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          xml:
            wrapped: true
        status:
          type: string
          description: pet status in the store
          enum:
          - available
          - pending
          - sold
        availableInstances:
          type: integer
          format: int32
          example: 7
          exclusiveMaximum: 10
          exclusiveMinimum: 1
          swagger-extension: true
        petDetailsId:
          type: integer
          format: int64
          $ref: /components/schemas/petdetails#pet_details_id
        petDetails:
          $ref: /components/schemas/petdetails
      required:
      - name
      - photoUrls
      xml:
        name: Pet
    PetDetails:
      $id: /components/schemas/petdetails
      $schema: https://json-schema.org/draft/2020-12/schema
      $vocabulary: https://spec.openapis.org/oas/3.1/schema-base
      properties:
        id:
          type: integer
          format: int64
          $anchor: pet_details_id
          example: 10
        category:
          $ref: /#/components/schemas/Category
          description: PetDetails Category
        tag:
          $ref: /#/components/schemas/Tag
      xml:
        name: PetDetails
    Tag:
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: Tag
  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://petstore3.swagger.io/oauth/authorize
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets
    mutual_tls:
      type: mutualTLS
    api_key:
      type: apiKey
      name: api_key
      in: header
webhooks:
  newPet:
    post:
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              description: Webhook Pet
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received
            successfully

We're specifically interested in line 247 and 250

[char0n]

Minimal fixture:

{
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object"
      },
      "UserProfile": {
        "$id": "/components/schemas/petdetails",
        "type": "object",
        "properties": {
          "user": {
            "$ref": "/#/components/schemas/User"
          }
        }
      }
    }
  }
}

This fixture prove that the ApiDOM works correctly given this type of constructs.

[char0n]

From the perspective of ApiDOM, all existing dereference strategies now support resolving/dereferencing ApiDOM fragment with internal or external references (only external references were supported before).

[char0n]

Addressed for swagger-js in swagger-api/swagger-js#3050

[char0n]

Addressed for swagger-ui in swagger-api/swagger-ui#9020

[char0n]

The original definition for this issue contained issues based on wrong assumptions how reterievalURI works. Here is the version of the definition where these assumptions were corrected. This versions is now resolvable by Swagger tooling.

openapi: 3.1.0
info:
  title: Swagger Petstore - OpenAPI 3.1
  description: |-
    This is a sample Pet Store Server based on the OpenAPI 3.1 specification.
    You can find out more about
    Swagger at [http://swagger.io](http://swagger.io).
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0 AND (MIT OR GPL-2.0-only)
    identifier: Apache-2.0 AND (MIT OR GPL-2.0-only)
  version: "1.0"
  summary: Pet Store 3.1
  x-namespace: swagger
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
  - url: /api/v31
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: http://swagger.io
  - name: store
    description: Access to Petstore orders
    externalDocs:
      description: Find out more about our store
      url: http://swagger.io
  - name: user
    description: Operations about user
paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      operationId: updatePet
      requestBody:
        description: Pet object that needs to be updated in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in JSON Format
              required:
                - id
              writeOnly: true
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in XML Format
              required:
                - id
              writeOnly: true
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in XML Format
                readOnly: true
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in JSON Format
                readOnly: true
        "400":
          description: Invalid ID supplied
        "404":
          description: Pet not found
        "405":
          description: Validation exception
      security:
        - petstore_auth:
            - write:pets
            - read:pets
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in JSON Format
              required:
                - id
              writeOnly: true
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
              description: A Pet in XML Format
              required:
                - id
              writeOnly: true
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in XML Format
                readOnly: true
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in JSON Format
                readOnly: true
        "405":
          description: Invalid input
      security:
        - petstore_auth:
            - write:pets
            - read:pets
  /pet/{petId}:
    get:
      tags:
        - pets
      summary: Find pet by ID
      description: Returns a pet when 0 < ID <= 10.  ID > 10 or nonintegers will simulate
        API error conditions
      operationId: getPetById
      parameters:
        - name: petId
          in: path
          description: ID of pet that needs to be fetched
          required: true
          schema:
            type: integer
            format: int64
            description: param ID of pet that needs to be fetched
            exclusiveMaximum: 10
            exclusiveMinimum: 1
      responses:
        default:
          description: The pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in JSON format
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
                description: A Pet in XML format
        "400":
          description: Invalid ID supplied
        "404":
          description: Pet not found
      security:
        - petstore_auth:
            - write:pets
            - read:pets
        - api_key: []
components:
  schemas:
    Category:
      $id: /components/schemas/category
      description: Category
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: Category
    Pet:
      $id: /components/schemas/pet
      $schema: https://json-schema.org/draft/2020-12/schema
      description: Pet
      properties:
        id:
          type: integer
          format: int64
          example: 10
        category:
          $ref: /components/schemas/category
          description: Pet Category
        name:
          type: string
          example: doggie
        photoUrls:
          type: array
          items:
            type: string
            xml:
              name: photoUrl
          xml:
            wrapped: true
        tags:
          type: array
          items:
            $ref: /components/schemas/tag
          xml:
            wrapped: true
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
        availableInstances:
          type: integer
          format: int32
          example: 7
          exclusiveMaximum: 10
          exclusiveMinimum: 1
          swagger-extension: true
        petDetailsId:
          type: integer
          format: int64
          $ref: /components/schemas/petdetails#pet_details_id
        petDetails:
          $ref: /components/schemas/petdetails
      required:
        - name
        - photoUrls
      xml:
        name: Pet
    PetDetails:
      $id: /components/schemas/petdetails
      $schema: https://json-schema.org/draft/2020-12/schema
      $vocabulary: https://spec.openapis.org/oas/3.1/schema-base
      properties:
        id:
          type: integer
          format: int64
          $anchor: pet_details_id
          example: 10
        category:
          $ref: /components/schemas/category
          description: PetDetails Category
        tag:
          $ref: /components/schemas/tag
      xml:
        name: PetDetails
    Tag:
      $id: /components/schemas/tag
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: Tag
  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://petstore3.swagger.io/oauth/authorize
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets
    mutual_tls:
      type: mutualTLS
    api_key:
      type: apiKey
      name: api_key
      in: header
webhooks:
  newPet:
    post:
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              description: Webhook Pet
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received
            successfully