将 Open Api 3.0 yaml 导入 Postman 7.1

Question

我想将 open-api 3.0 yaml 文件导入 postman, v. 7.1.1.

我正在使用 darkaonline/l5-swagger 在 Laravel 中生成 OpenApi 3.0 文档。生成的 open-api 3.0 yaml 文件在粘贴到 editor.swagger.io 时会产生无错误的输出。 api 是根据 json:api 规范（或打算）编写的。将文件导入 postman (v 7.1.1) 时会生成此错误："Error while importing Open API 3.0: Could not import" 我读过的所有文档都说 postman 现在支持 open api 3.0。我尝试从 Zircote 的 github 加载 OpenApi 3.0 yaml 示例，它们导入得很好。不过，它们比我们的文档要简单得多。代码摘录：警告这是很多，但我觉得我需要提供足够的上下文（它实际上是完整文档的一小部分——文件长 2000 行）：

info:
  title: 'NAME OF MY API'
  version: 1.0.0
servers:
  -
    url: 'https://api.API.com/v1'
paths:
   /accounts:
    get:
      tags:
        - accounts
      summary: 'list accounts'
      operationId: 'App\Http\Controllers\v1\AccountsController::index'
      responses:
        200:
          description: 'A list of accounts'
          content:
            application/vnd.api+json:
              schema:
                required:
                  - data
                properties:
                  data:
                    description: 'Show all accounts for this request.'
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                        id:
                          type: string
                        attributes:
                          $ref: '#/components/schemas/account'
                        relationships:
                          properties:
                            persons:
                              type: array
                              items:
                                $ref: '#/components/schemas/relationship'
                          type: object
                        links:
                          $ref: '#/components/schemas/relationship/properties/links'
                      type: object
                  meta:
                    $ref: '#/components/schemas/meta'
                  links:
                    $ref: '#/components/schemas/links'
                type: object
        401:
          description: 'Unauthorized access'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
        404:
          description: 'No records found'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
      servers:
        -
          url: 'https://api.API.com/v1'
    post:
      tags:
        - accounts
      summary: 'new account'
      operationId: 'App\Http\Controllers\v1\AccountsController::store'
      responses:
        201:
          description: 'Successful save'
        401:
          description: 'Unauthorized access'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
        400:
          description: 'Bad request, save failed'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
      servers:
        -
          url: 'https://api.API.com/v1'
  '/accounts/{id}':
    get:
      tags:
        - accounts
      summary: 'get one account'
      operationId: 'App\Http\Controllers\v1\AccountsController::show'
      parameters:
        -
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: 'An account object'
          content:
            application/vnd.api+json:
              schema:
                properties:
                  type:
                    description: 'Display the specified resource.'
                    type: string
                  id:
                    description: 'Display the specified resource.'
                    type: string
                  attributes:
                    $ref: '#/components/schemas/account'
                  relationships:
                    description: 'Display the specified resource.'
                    properties:
                      persons:
                        description: 'Display the specified resource.'
                        type: array
                        items:
                          $ref: '#/components/schemas/relationship'
                    type: object
                  links:
                    $ref: '#/components/schemas/relationship/properties/links'
                type: object
        401:
          description: 'Unauthorized access'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
        404:
          description: 'Record not found'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
      servers:
        -
          url: 'https://api.API.com/v1'
    delete:
      tags:
        - accounts
      summary: 'remove account'
      operationId: 'App\Http\Controllers\v1\AccountsController::destroy'
      parameters:
        -
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: 'An account object'
        401:
          description: 'Unauthorized access'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
        405:
          description: 'Method not allowed'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
        400:
          description: 'Bad request, save failed'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
      servers:
        -
          url: 'https://api.API.com/v1'
    patch:
      tags:
        - accounts
      summary: 'update account'
      operationId: 'App\Http\Controllers\v1\AccountsController::update'
      parameters:
        -
          name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: 'An account object'
        401:
          description: 'Unauthorized access'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
        400:
          description: 'Bad request, save failed'
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/error-response'
      servers:
        -
          url: 'https://api.API.com/v1'
components:
  schemas:
    account:
      title: 'account object'
      description: 'A single account object.'
      required:
        - ur_account_id
        - name
        - address1
        - city
        - state
        - zip
        - country_code
        - phone
        - email
      properties:
        _id:
          description: 'Unique identifier to include in path to get a single record.'
          type: string
        ur_account_id:
          description: 'The unique account ID.'
          type: string
        name:
          description: 'The name associated with the account'
          type: string
        address_1:
          description: 'The street address for the account.'
          type: string
        address_2:
          description: 'The Suite number, PO Box Number, Floor Number, etc, for the account.'
          type: string
        city:
          description: 'The city the account is resides in.'
          type: string
        state:
          description: 'The two letter abbreviation of the state the account resides in'
          type: string
        zip:
          description: 'The Postal Code the account resides in.'
          type: string
        country_code:
          description: 'Country code associated with the account.'
          type: string
        phone:
          description: 'The phone number associated with the account.'
          type: string
        phone_alpha:
          description: 'The phone number associated with the account.'
          type: string
        email:
          description: 'Email associated with the account'
          type: string
        require_po:
          description: 'Whether the account requires a PO.'
          type: string
        status:
          description: 'Status of current account'
          type: boolean
tags:
  -
    name: accounts
    description: 'Everything about accounts'
    externalDocs:
      description: 'Find out more'
      url: 'http://admin.API.com/documents' ```

Answer 1

问题是在每个路径对象的服务器对象中，我只定义了基 URL，假设出于某种原因基 URL 将与路径连接。如果在路径对象中定义服务器对象，则必须对端点使用 FULL URL。它给了我特别是 /{id} 端点的错误，因为我定义了一个服务器对象中不存在的路径变量

将 Open Api 3.0 yaml 导入 Postman 7.1

Importing Open Api 3.0 yaml to Postman 7.1

yaml

json-api

postman

openapi

openapi-generator