Boost Your API Workflow: A Complete Guide to Installing and Using YApi with Swagger

Swagger is often criticized for its unattractive UI and limited features, but many tools can enhance it; YApi is one such powerful API management platform.

YApi Overview

YApi is an efficient, easy‑to‑use, feature‑rich API management platform that offers elegant interface management for developers, product managers, and testers. With over 18K stars on GitHub, it provides permission management, mock data, Swagger import, and more.

Installation

Environment Preparation

Deploying YApi locally requires Node.js and MongoDB.

Install Node.js (v12.14.0) from https://nodejs.org/dist/v12.14.0/node-v12.14.0-x64.msi.

Install MongoDB (v4.2.5) following the guide in the linked article.

Install yapi-cli

yapi-cli is the official installation tool that provides a visual interface for deploying YApi.

Use npm to install:

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

After successful installation, the console displays output (see image).

Start the visual deployment interface with yapi server.

yapi server

Install YApi

Install YApi via the visual interface at http://localhost:9090.

After installation, the console shows default admin credentials and address.

Start the YApi service with:

node vendors/server/app.js

Access YApi at http://localhost:3000 using the default admin account [email protected]:ymfe.org.

Usage

Import Data from Swagger

Log in with the admin account, create a group mall-tiny-group.

Create a project mall-tiny-swagger under the group.

Start the existing mall-tiny-swagger project; Swagger UI is available at http://localhost:8088/swagger-ui/.

In YApi's Data Management, configure the Swagger api‑docs path and import the data.

After import, view all interfaces under the Interface tab.

Interface Management

Open the "Add Product" interface to see detailed documentation.

Set the correct request host in Environment Configuration.

Install a Chrome cross‑origin request plugin (download link provided).

Obtain a token via the login interface and add an Authorization header in Settings → Environment Configuration.

After adding the token, authenticated interfaces return data correctly.

Mock Function

Modify mock JSON via Interface → Edit → Advanced Settings.

Each interface provides a mock URL for front‑end debugging before backend implementation.

Calling the mock URL returns test data that can be customized.

Swagger Auto Sync

Enable automatic synchronization via Settings → Swagger Auto Sync and choose one of three sync modes.

Permission Management

If new members join, how can they view the API documentation?

Register a member account, e.g., [email protected]:123456.

Log in as admin and add the user to the appropriate group via Member List → Add Member.

The member can then log in and access the relevant API documentation.

Summary

YApi combined with Swagger is indeed powerful; it resolves documentation viewing and auto‑sync issues, adds permission management for security, and its mock feature lets front‑end developers debug without backend implementation, although JSON support could be improved with collapsible display.

Reference

Official documentation: https://hellosean1025.github.io/yapi/documents/index.html

Project Source

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-swagger