Swagger OpenAPI 与捆绑文件有关的问题

Question

我正在使用

swagger-cli

将包含

openapi.yaml

的

refs

文件捆绑到子目录中的其他

.yaml

文件。当我启动服务器时，api 文档工作正常，没有任何问题，并显示所有架构、属性、描述、路由、参数等。但是，当我尝试调用任何端点时，它会失败并显示

TypeError

我用于 swagger-cli 的命令

swagger-cli bundle ./app/config/openapi.yaml --outfile _build/openapi.yaml --type yaml

主要 openapi.yaml 文件

openapi: 3.0.1
info:
  title: Toy App
  description: 'A toy app'
  version: 1.0.0
servers:
- url: http://localhost:4000
  description: 'Local development server'
tags:
- name: reports
  description: CRUD operations for reports
  externalDocs:
    description: Find out more
    url: http://swagger.io
paths:
  "/api/product/{productId}/prices":
    $ref: './products.yaml#/~1api~product~1%productId%7D~prices'

这是我的 products.yaml 文件

/api/product/{productId}/prices:
    get:
      tags:
      - prices
      summary: Gets all prices for a product
      description: Returns an array of prices for a product
      parameters:
        - $ref: './parameters.yaml#/parameters/ProductId'
      responses:
        '200':
          description: List of product prices fetched successfully
          content:
            'application/json':
              schema:
                $ref: './schema/product.yaml#/Products'
        '400':
          $ref: './responses.yaml#/responses/400'
        '401':
          $ref: './responses.yaml#/responses/401'
        '403':
          $ref: './responses.yaml#/responses/403'
        '404':
          $ref: './responses.yaml#/responses/404'

这是我在 _build 目录中创建的 openapi.yaml 文件

'/api/product/{productId}/prices':
    get:
      tags:
        - client
      summary: Gets all prices for a product
      description: Returns an array of prices for a product
      parameters:
        - $ref: '#/paths/~1product~1client~1%7BproductId%7D~1prices/parameters/0'
      responses:
        '200':
          description: List of product prices fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1products/post/responses/200/content/application~1json/schema'
        '400':
          $ref: '#/paths/~1api~1me/get/responses/400'
        '401':
          $ref: '#/paths/~1api~1me/get/responses/401'
        '403':
          $ref: '#/paths/~1api~1me/get/responses/403'
        '404':
          $ref: '#/paths/~1api~1me/get/responses/404'

这是我向端点发出 get 请求时的错误

TypeError: Cannot read properties of undefined (reading 'parameters'

我很困惑为什么 _build/openapi.yaml 文件中的参数 ref 明显与原始文件中的参数 ref 不同。任何帮助表示赞赏。 TIA

Answer 1

似乎您的 JSON 指针无效

试试这些

# openapi.yaml
openapi: 3.0.1
info:
  title: Toy App
  description: 'A toy app'
  version: 1.0.0
servers:
- url: http://localhost:4000
  description: 'Local development server'
tags:
- name: reports
  description: CRUD operations for reports
  externalDocs:
    description: Find out more
    url: http://swagger.io
paths:
  "/api/product/{productId}/prices":
    $ref: './products.yaml#/~1api~1product~1%7BproductId%7D~1prices'

# products.yaml
/api/product/{productId}/prices:
    get:
      tags:
      - prices
      summary: Gets all prices for a product
      description: Returns an array of prices for a product
      parameters:
        - $ref: './parameters.yaml#/parameters/ProductId'
      responses:
        '200':
          description: List of product prices fetched successfully
          content:
            'application/json':
              schema:
                $ref: './product.yaml#/Products'
        '400':
          $ref: './responses.yaml#/responses/400'
        '401':
          $ref: './responses.yaml#/responses/401'
        '403':
          $ref: './responses.yaml#/responses/403'
        '404':
          $ref: './responses.yaml#/responses/404'

#parameters.yaml
parameters:
  ProductId:
    name: productId
    in: path
    required: true
    schema:
      type: string

#product.yaml
Products:
  type: object
  title: A Product Title
  description: A Product Description
  required:
    - ProductId
    - ProductType
  properties:
    ProductId:
      type: string
    ProductType:
      type: object
      properties:
        code:
          type: string
        name:
          type: string