创建 swagger （一)

安装、创建swagger

// 全局 安装 swagger 环境
npm install -g swagger
// 查看
swagger -V
// 下载项目
swagger project create YourProjectName
// 运行
node app.js

• 使用 express 框架
  
• 运行
  cd ./FirstSwagger
  node ./app.js
  
• 浏览器视图
  
• 目录结构
  
  swagger 链接

下载 swagger-tools

运行后在浏览器显示 api 文档

// 下载 
npm i swagger-tools

• 修改 app.js

// app.js
let fs = require('fs'),
    path = require('path');
let jsyaml = require('js-yaml');
let swaggerTools = require('swagger-tools')

var spec = fs.readFileSync(path.join(__dirname,'api/swagger/swagger.yaml'), 'utf8');
var swaggerDoc = jsyaml.safeLoad(spec);

SwaggerExpress.create(config, function(err, swaggerExpress) {
  if (err) { throw err; }

  // install middleware
  swaggerExpress.register(app);
  var port = process.env.PORT || 10010;
  // 加入 swaggerTools.initializeMiddleware
  swaggerTools.initializeMiddleware(swaggerDoc, function (middleware) {
        // Interpret Swagger resources and attach metadata to request - must be first in swagger-tools middleware chain
        app.use(middleware.swaggerMetadata());
        // Validate Swagger requests
        app.use(middleware.swaggerValidator());
        // Route validated requests to appropriate controller
        //app.use(middleware.swaggerRouter(options));
        // Serve the Swagger documents and Swagger UI
        app.use(middleware.swaggerUi());
        //var port = process.env.PORT || hfc.getConfigSetting('port');
        var port = config.port || 10010
        app.listen(port);
    });

   if (swaggerExpress.runner.swagger) {
     console.log('try this:\ncurl http://127.0.0.1:' + port + '/docs');
   }
});

• 浏览器运行视图
  由于更改了 node 代码，所以需要重新运行 node 环境
  
  在浏览器的视图
  
  一般我们都会修改swagger 的 basePath 为 /api/v1
  api/swagger/swagger.yaml
  则之后调用的接口则为：http://127.0.0.1:10010/api/v1/hello
  

在 api/swagger/swagger.yaml 中，编写相对应的接口文档

paths:
  /user/register:
    post:
      tags:
      - "User"
      #deprecated: true
      summary: 1.1 用户注册
      description: 用户注册接口
      operationId: userRegisterPOST
      parameters:
        - in: body
          name: body
          description: 注册信息
          required: true
          schema:
            $ref: "#/definitions/UserRegister"
      responses:
        "200":
          description: 返回信息
          schema:
            $ref: "#/definitions/NormalResponse"
    x-swagger-router-controller: "User"
definitions:
  UserRegister:
    required:
      - regtype
      - usertype
      - username
      - verifycode
    properties:
      regtype:
        description: 注册类型 1-手机号 2-用户名
        type: integer
        enum: [1, 2]
        default: 1
      usertype: 
        description: 用户类型 1-个人 2-企业
        type: integer
        enum: [1, 2]
        default: 1
      username:
        description: 用户名/手机号
        type: string
        default: "13412357896"
      verifycode:
        description: 验证码
        type: string
        default: ""
          
  NormalResponse:
    required:
      - code
      - message
    properties:
      code:
        description: 返回码
        type: integer
        default: 0
      message:
        description: 返回描述信息
        type: string
        default: "success"

之后添加更加的接口可以在 api/controllers 文件夹中创建对应的 js 文件来写相应的接口及接口的相应逻辑。

本人的 github 地址