Yaml

Question

我创建了一个简单的 API，但是我在使用 Swagger 记录它时遇到问题，因为我收到错误：第 200 行的重复映射键。该行显示：“INVALID TOKEN”更新开关的路由：api/switches/update/{id} 我也尝试过创建特定于更新的定义，但它与 Create 相同，所以我认为也可以使用 Create 定义进行更新。不确定，这是否是问题的一部分。

swagger: "2.0"
info:
version: "1.0.0"
title: Mechanical Switches API
host: localhost:4000
basePath: /
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
  - application/xml
  - text/xml
  - text/html
paths:
  /api/welcome:
    get:
      description: Sharing the love with welcome message
      summary: Welcome message
      operationId: getWelcomeMessage
      tags:
        - user
      responses:
        '200':
          description: "OK"
  /api/user/register:
    post:
      description: Register a new user
      summary: Create new user
      operationId: postNewUser
      tags:
        - user
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
      parameters:
        - in: body
          name: User registration
          description: The user to create
          schema:
            $ref: "#/definitions/userCreate"
  /api/user/login:
    post:
      description: Login as user
      summary: Login user
      operationId: loginExistingUser
      tags:
        - user
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
      parameters:
        - in: body
          name: User login
          description: The user to login
          schema:
            $ref: "#/definitions/userLogin"
  /api/switches/create:
    post:
      description: Create a new switch
      summary: New Switch
      operationId: postNewSwitch
      tags:
        - switches
      responses:
        '200':
          description: "OK"
        '400':
          description: "ACCESS DENIED"
        '401':
          description: "INVALID TOKEN"
      parameters:
        - in: body
          name: Create switch
          description: Create a new switch
          schema:
            $ref: "#/definitions/switchCreate"
  /api/switches:
    get:
      description: Get all the switches
      summary: All Switches
      operationId: getAllSwitches
      tags:
        - switches
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      description: Get a specific switch
      summary: Specific switch
      operationId: getSingleSwitch
      tags:
        - switches
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/type/linear:
    get:
      description: Get all linear switches
      summary: Linear switches
      operationId: getLinearSwitches
      tags:
        - switches
        - type linear
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/type/tactile:
    get:
      description: Get all tactile switches
      summary: Tactile switches
      operationId: getTactileSwitches
      tags:
        - switches
        - type tactile
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/type/clicky:
    get:
      description: Get all clicky switches
      summary: Clicky switches
      operationId: getClickySwitches
      tags:
        - switches
        - type clicky
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/mount/5pin:
    get:
      description: Get all switches with 5-pin mount
      summary: All 5-pin
      operationId: getAll5pin
      tags:
        - switches
        - 5pin
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/mount/3pin:
    get:
      description: Get all switches with 3-pin mount
      summary: All 3-pin
      operationId: getAll3pin
      tags:
        - switches
        - 3pin
      responses:
        '200':
          description: "OK"
        '400':
          description: "NOT OK"
  /api/switches/update/{id}:
    put:
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      description: Update a specific switch
      summary: Update switch
      operationId: updateSwitch
      tags:
        - switches
        - update
      responses:
        '200':
          description: "OK"
        '400':
          description: "ACCESS DENIED"
        '401':
          description: "INVALID TOKEN"
      parameters:
        - in: body
          name: Update existing switch
          description: Update a switch
          schema:
            $ref: "#/definitions/switchCreate"
  /api/switches/delete/{id}:
    delete:
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      description: Delete a specific switch
      summary: Delete switch
      operationId: deleteSwitch
      tags:
        - switches
        - delete
      responses:
        '200':
          description: "OK"
        '400':
          description: "ACCESS DENIED"
        '401':
          description: "INVALID TOKEN"
definitions:
  userCreate:
    properties:
      userName:
        type: string
      email:
        type: string
      password:
        type: string
    required:  
      - userName
      - email
      - password
  userLogin:
    properties:
      email:
        type: string
      password:
        type: string
    required:
      - email
      - password
  switchCreate:
    properties:
      model:
        type: string
      brand:
        type: string
      switchCollection:
        type: string
      switchType:
        type: string
      actuationForce:
        type: string
      preTravel:
        type: string
      totalTravel:
        type: string
      stemStructure:
        type: string
      mount:
        type: string
      lifespan:
        type: string
      colors:
        type: string
      manufacturer:
        type: string
    required:
      - model
      - brand
      - switchCollection
      - switchType
      - actuationForce
      - preTravel
      - totalTravel
      - stemStructure
      - mount
      - lifespan
      - colors
      - manufacturer

Answer 1

出现“重复映射键”错误是因为 /api/switches/update/{id} 定义包含两个 parameters 部分：

  /api/switches/update/{id}:
    put:
      parameters:    # <------
        - name: id
          in: path
          required: true
          type: integer
          format: int64
      description: Update a specific switch
      ...
      responses:
        ...
      parameters:    # <------
        - in: body
          name: Update existing switch
          description: Update a switch
          schema:
            $ref: "#/definitions/switchCreate"

您需要将参数合并到一个列表中：

  /api/switches/update/{id}:
    put:
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          format: int64
        - in: body
          name: Update existing switch
          description: Update a switch
          schema:
            $ref: "#/definitions/switchCreate"

Yaml - Swagger，重复映射键

Yaml - Swagger, Duplicate mapping key

swagger

openapi

swagger-2.0