Rapid API Development with magic-api: From Setup to Swagger Integration

magic-api

is a Java‑based rapid API development framework that generates HTTP endpoints via its UI, eliminating the need for explicit Controller, Service, DAO, Mapper, XML, or VO classes.

Setup

Add the magic-api-spring-boot-starter dependency (v1.0.2) to pom.xml:

<dependency>
  <groupId>org.ssssssss</groupId>
  <artifactId>magic-api-spring-boot-starter</artifactId>
  <version>1.0.2</version>
</dependency>

Configure the datasource and magic-api settings in application.yml. Example:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/magic_api?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: root

magic-api:
  web: /magic/web               # UI entry point
  resource:
    type: database               # storage type (file, database, redis)
    tableName: magic_api_file     # table for API definitions
    prefix: /magic-api
    readonly: false
    sql-column-case: camel
  page-config:
    size: size
    page: page
    default-page: 1
    default-size: 10

Create the required MySQL tables. magic_api_file stores API definitions, and a sample pms_brand table is used for CRUD demos.

CREATE TABLE `magic_api_file` (
  `id` bigint(255) NOT NULL AUTO_INCREMENT,
  `file_path` varchar(255) DEFAULT NULL,
  `file_content` text,
  PRIMARY KEY (`id`)
);

CREATE TABLE `pms_brand` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `big_pic` varchar(255) DEFAULT NULL,
  `brand_story` varchar(255) DEFAULT NULL,
  `factory_status` bit(1) DEFAULT NULL,
  `first_letter` varchar(255) DEFAULT NULL,
  `logo` varchar(255) DEFAULT NULL,
  `name` varchar(255) DEFAULT NULL,
  `product_comment_count` int(11) DEFAULT NULL,
  `product_count` int(11) DEFAULT NULL,
  `show_status` bit(1) DEFAULT NULL,
  `sort` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=9 DEFAULT CHARSET=utf8mb4;

CRUD API Definitions (using Magic Script)

Create – POST

/create

return db.table('pms_brand').insert(body);

Read by ID – GET

/detail/{id}

return db.table('pms_brand').where().eq('id', path.id).selectOne();

Update – POST

/update

return db.table('pms_brand').primary('id', body.id).update(body);

Paginated list – GET

/page

return db.table('pms_brand').page();

Delete – POST

/delete/{id}

return db.update('delete from pms_brand where id=#{id}');

Parameter Validation

Import the assert module and use its methods to enforce required fields.

import assert;
assert.notEmpty(body.name, 400, 'Name cannot be empty!');
assert.notEmpty(body.firstLetter, 400, 'First letter cannot be empty!');
return db.table('pms_brand').insert(body);

Result Transformation

Map query results to custom structures, e.g., converting a status flag to a readable string.

var list = db.table('pms_brand').select();
return list.map(item => ({
  name: item.name,
  firstLetter: item.firstLetter,
  showStatus: item.showStatus ? 'Not Display' : 'Display'
}));

Transaction Support

Wrap multiple operations in db.transaction() for atomic execution.

import assert;
var result = db.transaction(() => {
  var exist = db.table('pms_brand').where().eq('id', body.id).selectOne();
  assert.notNull(exist, 404, 'Brand not found!');
  db.table('pms_brand').primary('id', body.id).update(body);
  return 'ok';
});
return result;

Swagger Integration

Add Swagger dependencies to pom.xml:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

Configure Swagger under magic-api.swagger-config in application.yml:

magic-api:
  swagger-config:
    name: MagicAPI Test Interface
    title: MagicAPI Swagger Docs
    description: Documentation for MagicAPI demo APIs
    version: 1.0
    location: /v2/api-docs/magic-api/swagger2.json

Swagger UI is available at http://localhost:8080/swagger-ui.html.

Project Repository

https://gitee.com/ssssssss-team/magic-api