如何使用 express 设置 Swagger？

Question

我正在使用{swagger-express} library and my code is all in CoffeeScript。对于我的定义，我有：

app.use swagger.init app,
  apis: ['./src/routes.coffee', './src/models.yml']
  apiVersion: '0.1.0'
  basePath: "http://localhost:#{port}"
  info:
    title: 'My API'
    description: 'A complete listing of all API functions'
  swaggerUI: path.join __dirname, 'public'
  swaggerURL: '/swagger'

require('./src/routes') app

在routes中，我有：

  ###
   * @swagger
   * path: /login
   * operations:
   *   -  httpMethod: POST
   *      summary: Login with username and password
   *      notes: Returns a user based on username
   *      responseClass: User
   *      nickname: login
   *      consumes:
   *        - text/html
   *      parameters:
   *        - name: username
   *          description: Your username
   *          paramType: query
   *          required: true
   *          dataType: string
   *        - name: password
   *          description: Your password
   *          paramType: query
   *          required: true
   *          dataType: string
  ###

而且效果很好。我的 model.yml 文件是：

definitions:
  User:
    properties:
      user_id:
        type: string
        description: Unique ID to represent the user
      first_name:
        type: string
        description: First name of the Uber user.
      last_name:
        type: string
        description: Last name of the Uber user.
      email:
        type: string
        description: Email address of the Uber user
      picture:
        type: string
        description: Image URL of the Uber user.
      promo_code:
        type: string
        description: Promo code of the Uber user.

但这并没有出现在 api-docs.json 中。我试图在一个文件中定义 models，在另一个文件中定义 paths。可以吗？

Answer 1

我认为它行不通，因为每种格式都是单独读取并保存在使用 resourcePath 作为键的散列中。

https://github.com/fliptoo/swagger-express/blob/a5560af936e5398affe36d347af5be2a1bb64fc2/lib/swagger-express/index.js#L27

相同 resourcePath 的任何进一步声明将覆盖先前的声明。

我使用更新的 yml 格式进行了测试，其中包含 resourcePath、名称 models 而不是 definitions 以及模型的唯一 id。这使得模型出现了，但 none 我的其他信息：/

resourcePath: /login
models:
  User:
    id: User
    properties:
      user_id:
        type: String
        description: Unique ID to represent the user
      first_name:
        type: String
        description: First name of the Uber user.
      last_name:
        type: String
        description: Last name of the Uber user.
      email:
        type: String
        description: Email address of the Uber user
      picture:
        type: String
        description: Image URL of the Uber user.
      promo_code:
        type: String
        description: Promo code of the Uber user.

他们 github 上的示例使它看起来可行，但我无法实现。

如何使用 express 设置 Swagger？

How to set up Swagger with express?

coffeescript

swagger

swagger-ui