swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.47k stars 8.96k forks source link

OpenAPI 3.1.0 support: Individual path method reference not resolving. #8955

Open preader5705 opened 1 year ago

preader5705 commented 1 year ago

Q&A (please complete the following information)

Content & configuration

Swagger/OpenAPI definition:

In oas_paths.yaml:
openapi: 3.1.0
info:
  version: 1.0.0
  title: Customer Paths
paths:
  "/customer":
    get:
      ...

    post:
      ...

In oas_main.yaml:
openapi: 3.1.0
info:
  version: 1.0.0
  title: Customers

paths:
  # This works, including both the get and post methods for this path.
  "/customer":
    $ref: './oam_paths.yaml#/paths/~1customer'

  # This does NOT work to include just the get method:
  "/customer":
    get:
      $ref: './oam_paths.yaml#/paths/~1customer/get'

Swagger-UI configuration options:

Using out-of-the-box docker image.

In docker-compose file:

image: swaggerapi/swagger-ui:v5.1.0
?yourQueryStringConfig

Screenshots

image

How can we help?

When I use https://www.npmjs.com/package/@apidevtools/swagger-parser to bundle the spec into a single document, I can include just the get method and it renders as expected using swagger-ui, so is this a bug in swagger-ui that it is not resolving this reference correctly?

preader5705 commented 1 year ago

As of swagger-ui v5.4.2, this still doesn't work.

preader5705 commented 11 months ago

As of swagger-ui v5.10.1, this still doesn't work and I haven't found a workaround to this issue. i.e. if I have a common path definition with multiple methods (get, put, etc), there doesn't appear to be any way to include that path in a spec with just a subset of the defined methods.