API Reference
Relevant source files
The following files were used as context for generating this wiki page:
- zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java
- zheng-api/zheng-api-common/src/main/java/com/zheng/api/common/constant/ApiResult.java
- zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java
- zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsArticleController.java
- zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsTopicController.java
- zheng-cms/zheng-cms-common/src/main/java/com/zheng/cms/common/constant/CmsResult.java
- zheng-admin/src/index.html
The zheng project exposes a set of RESTful APIs to provide access to its various subsystems, including the User Permission Management System (UPMS) and the Content Management System (CMS). These APIs are the primary method for front-end applications and external services to interact with the platform's data and functionality, such as handling single sign-on (SSO), managing users, and performing CRUD operations on content like articles and topics.
The API layer is designed with a modular approach, where each subsystem (e.g., zheng-upms-server, zheng-cms-admin) contains its own set of controllers that define the endpoints. The system uses Swagger for API documentation, as indicated by the @Api and @ApiOperation annotations in the controller classes. All API responses follow a standardized format for consistency and easier client-side handling.
Sources: zheng-admin/src/index.html:124-125, zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsArticleController.java:36, zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java:33
Standard API Response
All API endpoints return a standardized JSON object. The base structure is defined in ApiResult, with specialized versions like CmsResult for specific modules. This ensures that clients can reliably parse responses and check for success or error states.
Sources: zheng-api/zheng-api-common/src/main/java/com/zheng/api/common/constant/ApiResult.java, zheng-cms/zheng-cms-common/src/main/java/com/zheng/cms/common/constant/CmsResult.java
Response Structure
The following diagram illustrates the class structure for API responses.
This diagram shows that CmsResult is a specialized form of the base ApiResult.
Sources: zheng-api/zheng-api-common/src/main/java/com/zheng/api/common/constant/ApiResult.java:13-18, zheng-cms/zheng-cms-common/src/main/java/com/zheng/cms/common/constant/CmsResult.java:13
The fields in the response object are detailed below:
| Field | Type | Description |
|---|---|---|
code | int | A status code indicating the result of the operation. |
message | String | A human-readable message describing the result. |
data | Object | The payload of the response, if any. |
timestamp | long | The server timestamp when the response was generated. |
Sources: zheng-api/zheng-api-common/src/main/java/com/zheng/api/common/constant/ApiResult.java:14-18
Key API Controllers
The system's functionality is exposed through several key controllers, each responsible for a specific domain.
| Controller | Module | Description |
|---|---|---|
SSOController | zheng-upms-server | Handles Single Sign-On (SSO) and authentication. |
CmsArticleController | zheng-cms-admin | Manages CRUD operations for articles in the Content Management System. |
CmsTopicController | zheng-cms-admin | Manages CRUD operations for topics in the Content Management System. |
TestController | zheng-api-server | Provides a basic test endpoint for the API server. |
Sources: zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java, zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsArticleController.java, zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsTopicController.java, zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java
UPMS API
The User Permission Management System (UPMS) API provides core authentication services.
Sources: zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java
SSOController
This controller manages the single sign-on process.
POST /sso/login
Authenticates a user and initiates a session.
Parameters:
| Name | Type | In | Description |
|---|---|---|---|
username | String | Query | The user's username. |
password | String | Query | The user's password. |
rememberMe | String | Query | A flag to indicate if the session should be remembered. |
backurl | String | Query | The URL to redirect to after a successful login. |
Login Flow:
The following sequence diagram illustrates the login process.
This diagram shows the user authentication flow, including user lookup, password validation, logging, and session creation.
Sources: zheng-upms/zheng-upms-server/src/main/java/com/zheng/upms/server/controller/SSOController.java:41-76
CMS API
The Content Management System (CMS) API provides endpoints for managing content such as articles and topics. These controllers use FluentValidator for input validation before processing requests.
Sources: zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsArticleController.java, zheng-cms/zheng-cms-admin/src/main/java/com/zheng/cms/admin/controller/manage/CmsTopicController.java
CmsArticleController
This controller handles all operations related to articles.
GET /manage/article/list
Retrieves a paginated list of articles.
Request Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
offset | int | 0 | The starting index for pagination. |
limit | int | 10 | The number of records to return. |
sort | String | null | The field to sort by. |
order | String | null | The sort order (asc or desc). |
Response:
A JSON object containing rows (a list of articles) and total (the total number of articles).
POST /manage/article/create
Creates a new article. The request body should contain the CmsArticle object.
Flow Diagram:
This diagram shows the process of creating a new article, including validation and persistence.
Other CmsArticleController Endpoints
GET /manage/article/index: Returns the view for the article management index page.GET /manage/article/create: Returns the view for the article creation page, populating it with a list of topics.GET /manage/article/delete/{ids}: Deletes one or more articles by their IDs.GET /manage/article/update/{id}: Returns the view for the article update page, populated with article and topic data.POST /manage/article/update/{id}: Updates an existing article.
CmsTopicController
This controller is responsible for managing topics, which are used to categorize articles. Its structure and endpoints are very similar to CmsArticleController.
Key Endpoints
GET /manage/topic/list: Retrieves a paginated list of topics.POST /manage/topic/create: Creates a new topic.GET /manage/topic/delete/{ids}: Deletes one or more topics by their IDs.POST /manage/topic/update/{id}: Updates an existing topic.
API Test Controller
A simple controller exists in the zheng-api-server module for testing purposes.
TestController
GET /api/test
A basic endpoint to verify that the API server is running. It returns a simple ApiResult object.
// zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java:23-27
@RequestMapping("/test")
@ResponseBody
public Object test() {
return new ApiResult(ApiResultConstant.SUCCESS, "test");
}
Sources: zheng-api/zheng-api-server/src/main/java/com/zheng/api/server/controller/TestController.java:23-27