Getting YApi Running on Linux: Installation, Usage, and Common Fixes

YApi is an API management platform aimed at developers, product staff, and testers. It gives a team a shared place to create, publish, and maintain API documentation, with an interface that depends on forms and click-driven tools instead of hand-written files. In practice, backend developers write the interface definitions, and frontend developers read the same definitions while building against them.

The steps below assume Linux and install the dependencies first.

Install Node.js 7.6+

Download a Node.js package from https://nodejs.org/en/download/, then upload it to the Linux server over FTP or download it directly on the server:

wget https://nodejs.org/dist/v12.16.3/node-v12.16.3-linux-x64.tar.xz

Extract it:

tar xf node-v12.16.3-linux-x64.tar.xz

The extracted bin directory contains commands such as node and npm. Create symlinks with ln:

ln -s /usr/local/node-v12.16.3-linux-x64/bin/npm /usr/local/bin
ln -s /usr/local/node-v12.16.3-linux-x64/bin/node /usr/local/bin

Check that the installation works:

node -v
npm -v

Install MongoDB 2.6+

Download MongoDB from https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-4.0.18.tgz or choose another version from https://www.mongodb.com/download-center/community. Upload the package to the Linux server if needed, then extract it:

tar -zxvf mongodb-linux-x86_64-4.0.18.tgz

Move it into place:

mv mongodb-linux-x86_64-4.0.18 /usr/local/mongodb

Edit the environment file:

vi /etc/profile

Add this at the bottom:

export PATH=$PATH:/usr/local/mongodb/bin

Create one directory for data and one for logs:

mkdir -p /data/db
mkdir -p /logs

Create a MongoDB configuration file. Go into the bin directory:

cd /usr/local/mongodb/bin

Create mongodb.conf:

vi mongodb.conf

Paste in the following configuration:

dbpath = /data/db # directory for data files
logpath = /logs/mongodb.log # directory for log files
port = 27017 # port
fork = true # run as a daemon in the background
noauth = true # disable security authentication
# auth=true # require authentication. If you uncomment this, you must create a MongoDB account and use the account and password for remote access. For a first install, it is recommended to keep this commented out.
bind_ip=0.0.0.0 # allow remote access, or comment this out; 127.0.0.1 allows only local access

Start MongoDB:

./mongod -f mongodb.conf

Check whether it started:

netstat -nltp|grep mongod

Or:

ps -ef | grep mongod

Set authentication or restrict MongoDB to local access. An open MongoDB instance can be discovered and wiped, and losing the data is a real risk.

Install yapi-cli

Install it online:

npm install -g yapi-cli --registry https://registry.npm.taobao.org

Configure YApi:

ln -s /usr/local/node-v12.16.3-linux-x64/bin/yapi /usr/bin/yapi

Start it:

yapi server

If the page does not load, open port 9090 and restart the firewall.

Open the port permanently:

firewall-cmd --zone=public --add-port=9090/tcp --permanent

Reload the firewall:

firewall-cmd --reload

Start yapi server again.

Enter the company name and leave the other settings at their defaults, then deploy.

After deployment succeeds, switch to the deployment directory and start the server with node vendors/server/app.js. Then open http://127.0.0.1:3000 in a browser.

Switch directory:

cd /usr/local/mongodb/bin/my-yapi/

Start the server:

node vendors/server/app.js

Or run it as a daemon:

node vendors/server/app.js &

Open http://127.0.0.1:3000. Remember to open port 3000 and reload the firewall.

To keep YApi running in the background, use PM2 or screen. PM2 is the option recommended by the official docs: https://pm2.keymetrics.io/docs/usage/quick-start/

Install PM2

npm install pm2@latest -g

Start the project with PM2

pm2 start /www/node-v10.16.0-linux-x64/my-yapi/vendors/server/app.js

The path after the command should point to the directory where YApi is installed.

Use YApi

Log in with the default account:

Account: [email protected] Password: ymfe.org

Only the super administrator can manage groups.

Create a group

Create a new project

Preview APIs

The interface also provides Mock addresses that the frontend can access directly. The backend only needs to define the API first; frontend development can then proceed against the Mock data before the real implementation is finished.

Add new members

Once the admin has created the project, developers can register accounts on the page and then view and maintain APIs.

All members register accounts:

Then the administrator adds them to the project group:

At that point all members can see the APIs. Log in with a member account to check:

Install the browser extension

After writing an API definition, you can test a local service directly from the browser, similar to testing an API in Postman.

Follow the instructions in the screenshot to install the browser extension:

Start a local project:

Test a GET request to user/test:

This can replace a separate Postman step for many checks.

Export data

When a project is finished, export the data for backup, for sharing, or for third-party use:

View the exported result:

There are many more features beyond those covered here.

Troubleshooting

Error: getaddrinfo ENOTFOUND yapi.demo.qunar.co

First confirm the Node.js version. A version that is too high will not work. The version used here is:

node: v10.16.0
npm: 6.9.0

Also confirm that the deployed YApi is the latest version. The version installed here was V1.10.9.

errmsg: 'command find requires authentication' when logging in

Check whether MongoDB has a user. If not, create one according to the actual installation location.

cd /www/mongodb/mongodb-linux-x86_64-4.0.18/bin

Create the user:

./mongo
# create a user with read/write permission
db.createUser(
  {
      user: 'yapi',
      pwd: 'xxx',
      roles: [ { role: "readWrite", db: "yapi" } ]
  }
)
exit

Restart MongoDB:

# kill the process first
ps -ef|grep mongodb
kill -9 具体进程id

# restart MongoDB
./mongod -f mongodb.conf

Redeploy YApi:

yapi server

At the final database step, enable authentication and enter the username and password.

If the same error still appears, the directory where the startup command is executed may be wrong. Verify it:

# enter the startup directory
 /www/node-v10.16.0-linux-x64/my-yapi/vendors/server/app.js

# start with node and try logging in to see whether an error occurs
node app.js

If login works this way, the issue is likely the working directory or permissions. Run the command from the current directory /www/node-v10.16.0-linux-x64/my-yapi/vendors/server/app.js, or use:

nohup node app.js &

Or:

pm2 start app.js

Log in again and the problem should be gone.

Usage documentation

https://hellosean1025.github.io/yapi/

The manual steps above are somewhat long. Docker can make YApi deployment much simpler, so it is worth considering if Docker is already part of your workflow.