OpenApi 3.0.2。规范文件没有路由器属性

Question

我正在尝试使用 OpenApi 3.0.2 为活动文档构建 API。我已经设法构建了一个经过验证的规范文件，如果我从 API 本身中取出所有 OpenApi “东西”，所有路由都可以正常工作，并且我没有错误（除非我设法改变了一些东西在尝试解决此问题时至关重要）。

此外，我的控制器实际上确实具有此错误建议我使用的通用控制器名称，所以我最初的想法是它无法找到我的控制器。但是，当我使用 Swagger 2.0 时（在使用 3.0 重建它之前），我没有遇到这个问题。

我的所有控制器的结构都类似，当我更改控制器的顺序时（首先是路径“/users”），我检索到了相同的错误（错误日志中的“用户”换成了“服装”）。

也就是说，我觉得我在“整合”功能 API 和有效规范文件时一定做错了什么。

我一直在寻找解决这个问题的方法，但我一无所获。如果这个问题以前被问过和回答过，我很抱歉；请重定向我。这是我的第一个 StackOverflow 问题，所以请保持温和。如果我遗漏了对问题重要的任何信息，请告诉我。

错误：

outfittr | 2019-01-21T13:51:37.150Z info: Valid specification file
outfittr | 2019-01-21T13:51:37.162Z info: Specification file dereferenced
outfittr | 2019-01-21T13:51:37.210Z info: No localhost or relative server found in spec file, added for testing in Swagger UI
outfittr | 2019-01-21T13:51:37.210Z debug: Register: GET - /garments
outfittr | 2019-01-21T13:51:37.211Z debug:   GET - /garments
outfittr | 2019-01-21T13:51:37.212Z debug:     Spec-file does not have router property -> try generic controller name: garmentsController
outfittr | 2019-01-21T13:51:37.212Z debug:     Controller with generic controller name wasn't found either -> try Default one
outfittr | 2019-01-21T13:51:37.212Z error:     There is no controller for GET - /garments
outfittr exited with code 0

openapi.yaml：

openapi: 3.0.2
info:
  version: "1.0.0"
  title: Outfittr API

paths:

  /swagger:
    x-swagger-pipe: swagger_raw

####################################### Garments ##############################################

  /garments:
    x-router-controller: garmentsController
    get:
      description: Returns an array of garments.
      operationId: indexGarments
      responses:
        "200":
          $ref: '#/components/schemas/Garment'
        default:
          $ref: "#/components/schemas/ErrorResponse"
    post:
      summary: Creates a new garment
      operationId: newGarment
      description: Adds garment to the system
      responses:
        '200':
          $ref: '#/components/schemas/Garment'
        default:
          $ref: "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Garment'
        description: User that was created.

  /garments/{_id}:
    x-router-controller: garmentsController
    get:
      description: Returns one garment
      operationId: viewGarment
      parameters:
        - in: path
          name: _id
          schema:
            type: string
          required: true
          description: Numeric ID of the user to get
      responses:
        "200":
          $ref: '#/components/schemas/Garment'
        default:
          $ref: "#/components/schemas/ErrorResponse"


######################################## Users ################################################

  /users:
    x-router-controller: usersController
    get:
      description: Returns an array of users.
      operationId: indexUsers
      responses:
        "200":
          $ref: '#/components/schemas/User'
        default:
          $ref: "#/components/schemas/ErrorResponse"
    post:
      summary: Creates a new user
      operationId: newUser
      description: Adds user to the system
      responses:
        '200':
          $ref: '#/components/schemas/User'
        default:
          $ref: "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
        description: User that was created.

  /users/{_id}:
    x-router-controller: usersController
    get:
      description: Returns one user
      operationId: viewUser
      parameters:
        - in: path
          name: _id
          schema:
            type: string
          required: true
          description: Numeric ID of the user to get
      responses:
        "200":
          $ref: '#/components/schemas/User'
        default:
          $ref: "#/components/schemas/ErrorResponse"

####################################### Wardrobe ##############################################

  /wardrobe:
    x-router-controller: wardrobeController
    get:
      description: Returns an array of garments in the user's wardrobe.
      operationId: indexWardrobeItems
      responses:
        "200":
          $ref: '#/components/schemas/WardrobeItem'
        default:
          $ref: "#/components/schemas/ErrorResponse"
    post:
      summary: Creates a new wardrobe item
      operationId: newWardrobeItem
      description: Adds garment to the user's wardrobe in the system
      responses:
        '200':
          $ref: '#/components/schemas/WardrobeItem'
        default:
          $ref: "#/components/schemas/ErrorResponse"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WardrobeItem'
        description: User that was created.

  /wardrobeItem/{_id}:
    x-router-controller: wardrobeController
    get:
      description: Returns one wardrobe item
      operationId: viewWardrobeItem
      parameters:
        - in: path
          name: _id
          schema:
            type: string
          required: true
          description: Numeric ID of the user to get
      responses:
        "200":
          $ref: '#/components/schemas/WardrobeItem'
        default:
          $ref: "#/components/schemas/ErrorResponse"

###################################### Components #############################################

servers:
  - url: outfittr.net
  - url: localhost:3000
components:
  schemas:
    User:
      type: object
      required:
        - _id
        - email
        - username
        - password
      properties:
        _id:
          type: string
          description: unique ID given by Mongo.
        firstName:
          type: string
          description: First name of the user.
        lastName:
          type: string
          description: Last name of the user.
        email:
          type: string
          description: User's email address.
        username:
          type: string
          description: User's username (for login)
        password:
          type: string
          description: User's password (for login).
        create_date:
          type: string
          description: date that the user joined.
        __v:
          type: integer
          description: I have no idea.

    Garment:
      type: object
      required:
        - _id
        - type
        - imageLink
      properties:
        _id:
          type: string
          description: unique ID given by Mongo.
        type:
          type: string
          description: type of garment
        imageLink:
          type: string
          description: primary color of garment
        __v:
          type: integer
          description: I have no idea.

    WardrobeItem:
      type: object
      required:
        - _id
        - owner_id
        - garment_id
      properties:
        _id:
          type: string
          description: unique ID given by Mongo.
        unavailable:
          type: boolean
          description: Is the wardrobe item dirty, loaned out, or otherwise unavailable?
        owner_id:
          type: string
          description: foreign key linking this wardrobe item to its owner.
        garment_id:
          type: string
          description: foreign key linking this wadrobe item to the garment it is.
        torn:
          type: boolean
          description: Is the wardrobe item torn?
        reserveDate:
          type: string
          description: Optional - a date for which this wardrobe item must be worn
        reserveTilDate:
          type: string
          description: Optional - a date after which the wardrobe item cannot be worn until the reserveDate.
        __v:
          type: integer
          description: I have no idea.

    ErrorResponse:
      required:
        - message
      properties:
        message:
          type: string

非常感谢任何帮助。

Answer 1

即使迟到了我也会回答这个问题，因为我遇到了同样的问题并寻找了很长时间的解决方案。如果其他人碰巧有任何关于如何修复它的参考。

当你在 oas-tools 中设置控制器参数时：

OasTools.configure({
    controllers: `${__dirname}/controllers`,
    ...
});

oas-tools 加载文件的默认映射是endpoint+Controller.js，在您的情况下，oas-tools 将在.../controllers/garmentsController.js 中查找导出函数indexGarments

另一个例子是/garments/{_ id}，控制器文件的名称应该是garments_idController.js

使用 x-router-controller

如果你想使用参数x-router-controller你必须把它放在方法里面：

...
  /garments:
    get:
      x-router-controller: garmentsController
      operationId: indexGarments
      description: Returns an array of garments.
      responses:

但要小心，因为它也会修改参数的值（不知道是bug还是文件名有这个要求） ，例如，如果您将x-router-controller 配置为garments.resource，则要搜索的文件将为.../controllers/garmentsresource.js

如果你设置了x-router-controller参数，但是找不到文件，会抛出这个错误：

info: Valid specification file
info: Specification file dereferenced
debug: Register: GET - /health
debug:   GET - /health
debug:     OAS-doc has x-router-controller property
error: undefined

Answer 2

对于 OAS3，你可以试试这个：

paths:
  /users:
    get:
      tags:
        - User
      
      x-openapi-router-controller: usersController
      description: Returns an array of users.
      operationId: indexUsers
      responses:
        "200":
          $ref: '#/components/schemas/User'