# YApi

:一个 API 管理网站,兼容 swagger 文档,且功能更多。

  • GitHub (opens new window)
  • 2018 年由去哪儿网开源。
  • 可用于管理大量 API 的文档,方便前后端开发人员联调。

# 部署

  • 用 docker-compose 部署:
    version: "3"
    
    services:
      mongo:
        container_name: mongo
        image: mongo:4.4.10
        restart: unless-stopped
        environment:
          MONGO_INITDB_ROOT_USERNAME: root
          MONGO_INITDB_ROOT_PASSWORD: ******
        networks:
          - net
        volumes:
          - /etc/localtime:/etc/localtime:ro
          - ./data:/data/db
    
      yapi:
        container_name: yapi
        image: yapipro/yapi:1.9.5
        init: true
        restart: unless-stopped
        command:
          - server/app.js
        networks:
          - net
        ports:
          - 80:80
        volumes:
          - ./config.json:/yapi/config.json
    
    networks:
      net:
    
    • 需要调整挂载目录的权限:
      chown -R 999 data
      
    • yapi 的配置文件 config.json 示例:
      {
        "port": "80",
        "closeRegister": true,              // 是否禁止新用户注册。目前 yapi 不支持管理员创建用户
        "adminAccount": "admin@test.com",   // 管理员的邮箱地址
        "db": {
          "connectString": "mongodb://mongo:27017/yapi?authSource=admin",
          "user": "root",
          "pass": "******"
        },
        "mail": {
          "enable": true,
          "host": "smtp.gmail.com",
          "port": 465,
          "from": "*",
          "auth": {
            "user": "xxx@test.com",
            "pass": "******"
          }
        }
      }
      
    • 初次部署时,需要初始化数据库:
      docker exec -it yapi node server/install.js
      
    • 忘记管理员密码时,需要到 MongoDB 中修改密码:
      docker exec -it mongo -u root -p
      use yapi
      db.user.update({'username':'admin'},{$set:{'password':'******'}});
      

# 用法

  • 支持搜索 API 。
  • 支持自动生成 Mock 接口。
    • 当用户调用 Mock 接口时,yapi 会返回一个模拟响应,其中的响应参数是基于 Mock.js 生成的随机值。
    • 用户可以通过两种方式配置 Mock 响应:
      • Mock.js 模板
      • JS 脚本
  • 支持创建多个项目。
  • 支持给一个项目定义多个配置环境,包括域名、Headers、全局变量。

# Swagger

  • Swagger 项目定义了一种接口描述语言,用于编写 HTTP API 的描述文档。
    • 该文档采用 JSON 或 YAML 格式。
    • 该文档容易被程序解析,但不方便供人阅读。
    • 2016 年,Swagger API 规范独立为一个项目,改名为 OpenAPI 。
  • Swagger 项目包含多个工具,比如:
  • Swagger 文档的部分示例:
    paths:
      /user:                      # API 路径
        post:
          summary: "Add a new user"
          description: ""
          consumes:               # request body 的类型
          - "application/json"
          produces:               # response body 的类型
          - "application/json"
          parameters:             # 输入参数
          - in: "body"            # 参数的位置,是在报文 body 还是 query
            name: "username"
            description: ""
            required: true
            type: "string"
          responses:              # 响应
            "200":
              description: "success"
            "405":
              description: "Invalid input"